본문으로 건너뛰기
Capgo logo
강좌

Capacitor 8을 사용하여 iOS & Android로 변환하는 방법

Transform your existing Next.js 15 web application into native iOS and Android mobile apps using Capacitor 8. A complete guide to configuring static export, adding native plugins, and deploying to app stores.

마틴 도나디우

작가

발레리아

리뷰어

조던

편집자

__CAPGO_KEEP_0__ 8을 사용하여 iOS & Android로 변환하는 방법

Capacitor 8을 사용하여 iOS & Android로 변환하는 방법

Introduction

Next.js 웹 애플리케이션이 이미 존재하는 경우? Capacitor 8 — 성능이 향상되고 새로운 기능이 포함된 최신 버전입니다.

Capacitor wraps your web app in a native container, giving you access to device APIs like camera, filesystem, and push notifications while keeping your existing React codebase. Unlike React Native, you don’t need to rewrite anything — your Next.js code runs as-is.

Capacitor는 웹 앱을 네이티브 컨테이너에.wrap하여 기기 API (카메라, 파일 시스템, 푸시 알림 등) 에 접근할 수 있도록 해주며, 기존의 React 코드베이스를 유지합니다. React Native와 달리, 다시 작성할 필요가 없습니다. — Next.js는 그대로 작동합니다.

  • What you’ll learn:
  • Add Capacitor 8 with essential native plugins
  • Capacitor 8에 필수 네이티브 플러그인을 추가합니다.
  • iOS 및 Android 시뮬레이터에서 빌드 및 테스트합니다.
  • 빠른 개발을 위해 라이브 리로드를 활성화합니다.
  • Add native-feeling UI with Capgo Native Navigation and Transitions

새로운 프로젝트를 시작하려면? Next.js로 모바일 앱을 처음부터 구축하는 방법.

Next.js와 Capacitor의 이점

  • Code 재사용: Next.js는 재사용 가능한 컴포넌트를 작성하고 웹 및 모바일 앱 간에 code를 공유할 수 있으므로 개발 시간과 노력을 절약할 수 있습니다.
  • 성능: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
  • : Next.js는 서버 사이드 렌더링 및 __CAPGO_KEEP_0__ 스플리팅과 같은 내장 성능 최적화 기능을 제공하여 빠른 로딩 시간과 smooth한 사용자 경험을 보장합니다.: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
  • 자연스러운 기능: Capacitor는 카메라, 위치 정보, 등과 같은 네이티브 장치 기능에 접근할 수 있으므로 기능-rich한 모바일 앱을 구축할 수 있습니다.

간소화된 개발

시작하기 전에 다음을 확인하세요:

  • Node.js 18 이상이 설치되어야 합니다. 설치되어야 합니다.
  • 이미 존재하는 Next.js 15 이상이 설치되어야 합니다. Next.js 애플리케이션
  • Xcode (iOS 개발을 위해 macOS만)
  • Android Studio (Android 개발을 위해)

Next.js 앱을 모바일로 구성하는 방법

첫 번째 단계는 Next.js 앱을 정적 내보내기로 구성하는 것입니다. Capacitor는 정적 HTML/JS/CSS 파일을 네이티브 앱으로 패키징하기 위해 필요합니다.

모바일 앱을 Native로 빌드하는 방법 next.config.js or next.config.ts파일을 열고 export 설정을 추가하세요:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

Next.js에서 output: 'export' Next.js는 정적 HTML 파일을 생성하고 서버를 필요로 하는 Next.js 이미지 최적화를 무시합니다. images: { unoptimized: true } 중요:

서버를 필요로 하는 기능(__CAPGO_KEEP_0__ 라우트, 서버 컴포넌트에 데이터를 불러오는 기능 등)을 사용 중이라면, 클라이언트 사이드 대안 또는 외부 API를 사용하여 리팩토링해야 합니다. If you’re using features that require a server (API routes, server components with data fetching, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

정적 export를 테스트하려면: package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "mobile": "bun run build && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

Native 앱에 포함될 정적 파일이 포함된 폴더가 프로젝트의 루트에 생성되어야 합니다.

bun run build

__CAPGO_KEEP_0__ out Capacitor

프로젝트에 Capacitor 8을 추가합니다.

Next.js 앱을 네이티브 모바일 컨테이너로 패키징하려면 다음 단계를 따르세요.

  1. Install Capacitor core and CLI:
bun add @capacitor/core
bun add -D @capacitor/cli
  1. Capacitor의 일반적인 플러그인을 설치하세요. 필요할 때:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferences

이러한 플러그인은 다음 기능을 제공합니다:

  • @capacitor/app: 앱 라이프 사이클 이벤트 (전경/배경, URL)를 처리합니다.
  • @capacitor/keyboard: 모바일 키보드 동작을 제어합니다.
  • @capacitor/splash-screen: 네이티브 스플래시 스크린을 관리합니다.
  • @capacitor/preferences: 데이터를 영구적으로 저장하세요.
  1. Initialize Capacitor with your project details:
bunx cap init my-app com.example.myapp --web-dir out

바꾸세요. my-app 앱 이름과 com.example.myapp 앱 ID (역 도메인 표기법)를 입력하세요.

  1. 파일에 적절한 구성으로 생성하거나 업데이트하세요: capacitor.config.ts 자연 플랫폼을 설치하세요:
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      showSpinner: false,
      splashFullScreen: true,
      splashImmersive: true,
    },
  },
};

export default config;
  1. 자연 플랫폼 폴더를 추가하세요:
bun add @capacitor/ios @capacitor/android
  1. Capgo는 프로젝트의 루트 폴더에 자연 프로젝트 폴더를 생성하고
bunx cap add ios
bunx cap add android

Capacitor will create ios and android folders at the root of your project containing the native projects.

Android 프로젝트를 만들려면 __CAPGO_KEEP_0__ Android StudioiOS의 경우 Mac에서 __CAPGO_KEEP_0__ Xcode.

  1. 프로젝트를 빌드하고 동기화하세요:
bun run mobile

이것은 Next.js 프로젝트를 빌드하고 정적 파일을 네이티브 플랫폼과 동기화하는 커스텀 스크립트를 실행합니다.

네이티브 앱 빌드 및 배포

네이티브 모바일 앱을 빌드하고 배포하려면 다음 단계를 따르세요: iOS 앱을 개발하려면 __CAPGO_KEEP_0__ Xcode 설치되어야 하며, Android 앱을 개발하려면 __CAPGO_KEEP_0__ Android Studio 설치되어야 합니다. 또한 앱 스토어에 앱을 배포하려면 iOS의 경우 Apple Developer Program에 등록하고 Android의 경우 Google Play Console에 등록해야 합니다.

  1. __CAPGO_KEEP_0__ __CAPGO_KEEP_1__

iOS용으로:

bun run mobile:ios

Android용으로:

bun run mobile:android

또는 직접 Capacitor CLI:

bunx cap open ios
bunx cap open android
  1. 앱을 빌드하고 실행하세요:

android-studio-run

  • Android Studio에서 프로젝트가 준비되기를 기다리십시오. 그런 다음 연결된 장치 또는 에뮬레이터에 앱을 배포하기 위해 "실행" 버튼을 클릭하십시오. xcode-run

  • Xcode에서 실제 장치에 앱을 배포하기 위해 서명 계정을 설정하십시오. 이 과정을 처음으로 진행하는 경우 Xcode는 Apple Developer Program에 가입한 경우에만 진행하도록 안내하십시오. 설정이 완료되면 "재생" 버튼을 클릭하여 연결된 장치에서 앱을 실행하십시오.

축하합니다! Next.js 웹 앱을 모바일 장치에 성공적으로 배포했습니다.

Next.js 모바일 앱
하지만, 개발 중에는 더 빠른 방법이 있습니다...

Capacitor Live Reload

개발 중에는 모바일 기기에서 즉시 변경 사항을 볼 수 있는 라이브 리로드 기능을 사용할 수 있습니다. 이 기능을 활성화하려면 다음 단계를 따르십시오.

  1. 개발 중인 기기 IP 주소를 찾으십시오.

  • macOS에서 터미널에서 다음 명령어를 실행하십시오.

    ipconfig getifaddr en0

  • Windows에서 다음 명령어를 실행하십시오.

    ipconfig

    출력에서 IPv4 주소를 찾으십시오.

  1. 개발 서버에 대한 capacitor.config.ts 개발 서버 주소로 바꾸십시오.
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
};

export default config;

개발 서버 주소에 YOUR_IP_ADDRESS 개발 서버 주소 (예를 들어 192.168.1.100).

  1. 개발 프로젝트에 변경 사항을 적용하십시오.
bunx cap copy

__CAPGO_KEEP_0__ copy 명령어는 웹 폴더와 구성 변경을 원본 프로젝트에 복사하고 전체 프로젝트를 업데이트하지 않습니다.

  1. Android Studio 또는 Xcode를 사용하여 앱을 다시 빌드하고 기기에서 실행하세요.

이제, Next.js 앱에 대한 변경 사항이 있으면 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.

Note: If you install new plugins or make changes to native files, you’ll need to rebuild the native project since live reloading only applies to web code changes.

Capacitor 플러그인 사용

Capacitor 플러그인은 네이티브 장치 기능에 접근할 수 있도록 Next.js 앱에서 사용할 수 있습니다. 예를 들어 Share 플러그인을 사용해 보겠습니다. Share 플러그인 설치 Share 플러그인을 사용하기 위해 파일을 업데이트하세요.

  1. 변경 사항을 네이티브 프로젝트와 동기화하세요.
bun add @capacitor/share
  1. __CAPGO_KEEP_0__ pages/index.js __CAPGO_KEEP_0__
import Head from 'next/head';
import styles from '../styles/Home.module.css';
import { Share } from '@capacitor/share';

export default function Home() {
  const share = async () => {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends',
    });
  };

  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to <a href="https://nextjs.org">Capgo!</a>
        </h1>

        <p className={styles.description}>
          <h2>Cool channel</h2>
          <button onClick={() => share()}>Share now!</button>
        </p>
      </main>
    </div>
  );
}
  1. __CAPGO_KEEP_0__

이전에서 언급한 바와 같이 새로운 플러그인을 설치할 때, sync 작업을 수행하고 앱을 다시 장치에 배포해야 합니다. 이 작업을 수행하려면 다음 명령어를 실행하세요:

bun run mobile

혹은 다시 빌드하지 않고만 sync를 수행하세요:

bunx cap sync
  1. 앱을 장치에 다시 배포하세요.

이제 “Share now!” 버튼을 클릭하면, native share dialog가 나타나고 다른 앱과 콘텐츠를 공유할 수 있습니다.

next-capacitor-share
다음으로, iOS 및 Android에서 Capgo 네비게이션과 전환을 사용하여 앱을 더 네이티브하게 만들 수 있고, 수평 스크롤이나 안전 영역이 잘려나가는 iOS 레이아웃 문제를 해결할 수 있습니다. ## 네이티브한 UI를 위한 Capgo 네이티브 네비게이션과 전환

여러 년 동안 Ionic 을 사용하여 크로스 플랫폼 애플리케이션을 개발해 왔지만, Next.js.

For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

설치:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

자연스러운 네이티브 네비게이션을 위해 CSS inset 모드를 구성하여 웹 콘텐츠가 네이티브 바를 존중하도록:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

리퀴드 글라스 탭 바를 렌더링하십시오 (iOS는 시스템 소유의 렌더링을 사용하고 Android는 흐릿한 WebView 배경을 사용합니다):

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  router.push(`/${id}`);
});

네이티브 페이지 전환을 앱 셸에 추가하십시오:

import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

페이지를 wrapping하여 cap-router-outlet, cap-page페이지를 wrapping하여 cap-content또는 setDirection('forward') 또는 setDirection('back') 또는 router.push() 또는 router.back()웹 헤더 또는 푸터를 중복하지 마십시오. 네이티브 네비게이션에서 이러한 표면을 소유한다.

자세한 설명서를 참조하십시오: Using @capgo/capacitor-native-navigation 및 Using @capgo/capacitor-transitions.

안전 영역에 Tailwind

디바이스의 안전 영역에 대한 Tailwind CSS를 사용하려면 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__에서 출판됨) tailwind-capacitor 다음과 같은 유용성과 다른 npm-친화적인 Tailwind 플러그인을 제공합니다: safe-areas Capacitor

bun add -D tailwind-capacitor

In styles/globals.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

사용할 수 있는 유틸리티 pt-safe, pb-safe, px-safe 대신 env(safe-area-inset-*) 수동으로 open a PR on GitHub.

Next.js 설정에 필요한 것이 빠진 경우

__CAPGO_KEEP_0__ overflow-x: hidden PR을 열어보세요

iOS 레이아웃 문제 해결 (뷰포트, 안전 영역, 가로 스크롤)

iOS에서 콘텐츠가 잘려나거나-shifted 또는 가로 스크롤이 가능하다면 (app/추가적인 설정이나 뷰포트 태그만 조정하는 것만으로 해결되지 않는 경우입니다. 이러한 체크를 순서대로 진행해 보세요. 뷰포트 메타 태그가 올바르게 적용되어 있는지 확인하세요. App Router viewport from app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

Pages Router (pages/viewport meta 태그를 넣어 주세요 pages/_app.tsx아니요 _document.tsx (Next.js는 viewport 동작에 대한 태그를 기대하는 방식과 다를 수 있습니다.) _document.tsx iOS 안전 영역을 한 번에 처리하세요

싱글 앱 셸을 만들고 안전 영역 패딩을 거기에 적용하세요 — 여러 개의 중첩된 컴포넌트에 적용하지 마세요:

모든 페이지 콘텐츠를

html,
body,
#__next {
  width: 100%;
  min-height: 100%;
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}

* {
  box-sizing: border-box;
}

.app-shell {
  min-height: 100dvh;
  width: 100%;
  padding-top: env(safe-area-inset-top);
  padding-right: env(safe-area-inset-right);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
}

. 중복된 안전 영역 패딩이 헤더, 모달, 레이아웃 wrapper에 적용되어 UI가 잘린 것처럼 보이거나 너무 크게 보이는 경우가 있습니다. .app-shell그리고

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitor그것을 표현하는 동일한 패딩을 utilities와 함께 pt-safe pb-safe px-safe 단일 셸에서

Capacitor iOS contentInset Live Update Dynamic Label To never 첫 번째

In capacitor.config.tsCSS (또는 Native Navigation의) contentInsetMode: 'css'__CAPGO_KEEP_0__의 자동 콘텐츠 인셋과 CSS 패딩을 혼합하는 것은 일반적인 두 배의 간격의 원인입니다.

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  ios: {
    contentInset: 'never',
  },
};

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) 일반적으로 요소가 사용하는 것

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__ 100vwTailwind w-screen픽셀 너비 min-width.

사파리 웹 인스펙터에서 실행하세요:

[...document.querySelectorAll('*')]
  .filter(el => el.scrollWidth > document.documentElement.clientWidth)
  .map(el => ({
    el,
    tag: el.tagName,
    class: el.className,
    scrollWidth: el.scrollWidth,
    clientWidth: document.documentElement.clientWidth,
  }));

Tailwind w-screen 대신 w-full 가능한 경우 Tailwind를 사용하세요. 100vw / w-screen수평 방향으로의 오버플로우 문제는

안전 영역의 중복된 패딩 또는 고정 너비 컨테이너에서 발생합니다.

To ensure optimal performance of your Next.js and Capacitor app, consider the following best practices:

  • Next.js 및 __CAPGO_KEEP_0__ 앱의 최적 성능을 보장하기 위해 다음의 최적화 방법을 고려하세요.
  • 사용하지 않는 의존성 및 자산을 제거하여 앱 크기를 최소화하세요.
  • 이미지 및 기타 미디어 파일을 최적화하여 로딩 시간을 줄이세요.
  • 서버 사이드 렌더링 (SSR)과 Next.js를 사용하여 앱의 로딩 속도와 검색 엔진 최적화 (SEO)를 향상하세요.
  • Capacitor의 내장 최적화 기능, 예를 들어 웹 뷰 캐싱과 앱 번들링을 활용하세요.

결론

Capacitor 8을 사용하여 기존의 Next.js 웹 애플리케이션을 iOS 및 Android 앱으로 성공적으로 변환했습니다. 웹 코드베이스는 이제 모바일 장치에서 실행되며 장치 API에 접근할 수 있습니다.

성공적으로 완료한 작업:

  • Next.js를 정적 내보내기 위해 구성했습니다.
  • Capacitor 8을 추가하여 필수 플러그인을 설치했습니다.
  • iOS 및 Android 시뮬레이터로 빌드 및 배포했습니다.
  • 개발 중에 라이브 리로드를 활성화했습니다.
  • iOS 레이아웃 문제를 해결했습니다 (뷰포트, 안전 영역, 오버플로우).
  • Capgo Native Navigation과 Transitions를 사용하여 네이티브한 느낌의 UI를 추가했습니다.

다음 단계:

  • 설정 Capgo Capacitor를 사용하여 Next.js와 함께 네이티브 모바일 앱을 빌드하는 방법
  • 오버 더 에어 업데이트 없이 앱 스토어 재제출 없이
  • 카메라, 위치 정보, 푸시 알림 등 더 많은 네이티브 플러그인을 추가하세요
  • 프로덕션용 앱 아이콘과 스플래시 스크린을 구성하세요

앱 스토어와 구글 플레이 제출을 위해 앱을 준비하세요 새로운 프로젝트를 시작하고 싶으세요? Next.js로 모바일 앱을 처음부터 구축하는 방법

자세한 가이드를 위해

Capgo를 사용하여 더 나은 앱을 더 빠르게 빌드하는 방법을 알아보세요. __CAPGO_KEEP_0__에 가입하세요. 오늘.

Capacitor 8을 사용하여 Convert Your Next.js 앱을 iOS &amp; Android로 계속 진행하세요.

__CAPGO_KEEP_0__를 사용하는 경우 iOS 및 Android 앱으로 변환하기: Capacitor 8 __CAPGO_KEEP_0__ 플러그인 작업을 계획하기 위해 연결하세요. Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우 Capacitor 플러그인들: Capgo Capacitor 플러그인들: Capgo의 구현 세부 사항 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항 Ionic Enterprise 플러그인 대체 Ionic Enterprise 플러그인 대체의 제품 워크플로우 Capgo 네이티브 빌드 Capgo 네이티브 빌드의 제품 워크플로우

Capacitor 앱에 대한 즉각적인 업데이트

Capgo 앱에 대한 즉각적인 업데이트 설명

Martin의 인간 지원

시작하기

최신 뉴스

Capgo는 여러분에게 모바일 앱을 정말 전문적으로 만들기 위해 필요한 최고의 통찰력을 제공합니다.

Capacitor 앱의 양방향 통신
개발 모바일 +1
2025년 4월 26일

Capacitor 앱에서 2방향 통신

OTA 업데이트를 피해야 하는 5가지 일반적인 실수
개발 보안 +1
2025년 4월 13일

OTA 업데이트를 피해야 하는 5가지 일반적인 실수

모바일 앱 라이브 업데이트를 위한 5가지 보안最佳 관행
개발 모바일 +1
2025년 1월 14일

모바일 앱 실시간 업데이트에 대한 5가지 보안最佳 관행

모든 블로그 글 보기