메인 콘텐츠로 건너뛰기
Capgo 로고
튜토리얼

Capacitor 8을 사용하여 iOS & Android로 변환하세요.

Capacitor 8을 사용하여 기존의 Next.js 15 웹 애플리케이션을 native iOS 및 Android 모바일 앱으로 변환하는 방법에 대한 완전한 가이드입니다. static export를 구성하고 native 플러그인을 추가하고 앱 스토어에 배포하는 방법을 배웁니다.

마틴 도나디유

마틴 도나디유

콘텐츠 마케터
Capacitor 8을 사용하여 iOS & Android로 변환하세요.

소개

기존의 Next.js 웹 애플리케이션이 있나요? 이 가이드에서는 __CAPGO_KEEP_0__을 사용하여 native iOS 및 Android 모바일 앱으로 변환하는 방법을 배웁니다. Capacitor 8 — 성능이 향상되고 새로운 기능이 추가된 최신 버전입니다.

Capacitor은 웹 앱을 네이티브 컨테이너에 감싸줌으로써 카메라, 파일 시스템, 푸시 알림과 같은 장치 API에 접근할 수 있게 해주며 기존의 React 코드베이스를 유지합니다. React Native와 달리, code을 사용하는 Next.js 앱은 기존의 코드를 다시 작성할 필요가 없습니다.

학습할 내용:

  • 기존의 Next.js 앱을 정적 내보내기로 구성합니다.
  • Capacitor 8과 필수 네이티브 플러그인을 추가합니다.
  • iOS 및 Android 시뮬레이터에서 빌드 및 테스트합니다.
  • 빠른 개발을 위해 라이브 리로드를 활성화합니다.
  • 옵션으로 Konsta UI를 추가하여 네이티브 보기에 적합한 컴포넌트를 사용합니다.

새로운 프로젝트를 시작하고 싶다면, Next.js 모바일 앱을 처음부터 구축하는 방법에 대한 가이드를 확인하세요..

Next.js와 Capacitor을 사용하는 이점

  • Code 재사용성: Next.js는 재사용 가능한 컴포넌트를 작성할 수 있게 해주며 웹 및 모바일 앱 간에 code을 공유할 수 있게 해주며 개발 시간과 노력을 절약할 수 있습니다.
  • 성능: Next.js는 서버 사이드 렌더링 및 code 분할과 같은 내장 성능 최적화 기능을 제공하여 빠른 로딩 시간과 smooth한 사용자 경험을 보장합니다.
  • 자연스러운 기능: Capacitor은 카메라, 위치 정보, 및 더 많은 기능을 제공하여 기능이 풍부한 모바일 앱을 빌드할 수 있도록 해줍니다.
  • 간소화된 개발: Capacitor을 사용하여 모바일 앱을 개발하고 테스트할 수 있으며, familiar한 웹 기술을 사용하여 학습 곡선이 줄어들고 개발 프로세스가 단순화됩니다.

사전 조건

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

  • Node.js 18+ 설치
  • 기존 Next.js 15+ 모바일 애플리케이션
  • Xcode (iOS 개발을 위해 macOS만)
  • Android Studio (Android 개발을 위해)

Next.js 앱을 모바일로 준비하는 방법

Next.js 앱을 정적으로 내보내기 위해 첫 단계는 Capacitor이 정적 HTML/JS/CSS 파일을 모아 native 앱으로 패키징할 수 있도록 하기 위한 설정입니다.

파일을 열고 next.config.js (또는 next.config.ts) 파일을 열고

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

module.exports = nextConfig;

Next.js 앱을 정적으로 내보내기 위해 output: 'export' 설정은 Next.js가 정적 HTML 파일을 생성하도록 지시합니다. images: { unoptimized: true } __CAPGO_KEEP_0__ 서버를 필요로 하는 기능을 사용 중이라면, __CAPGO_KEEP_0__ 루트 경로에 있는 static 폴더를 확인하세요. 이 폴더에는 __CAPGO_KEEP_0__이 네이티브 앱에 포함할 모든 정적 파일이 있습니다.

중요: 서버가 필요로 하는 기능을 사용 중이라면, 클라이언트 측 대안 또는 외부 API를 사용하여 API 루트 경로에 있는 static 폴더를 확인하세요. 이 폴더에는 API이 네이티브 앱에 포함할 모든 정적 파일이 있습니다.

Next.js 이미지 최적화를 bypass하는 __CAPGO_KEEP_0__를 사용합니다. 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"
  }
}

__CAPGO_KEEP_0__를 사용하여 모바일 전용 스크립트를 추가하세요.

bun run build

__CAPGO_KEEP_0__를 사용하여 정적 내보내기 테스트를 진행하세요. out Capacitor를 사용하여 정적 내보내기 테스트를 진행하세요.

Capacitor 루트 경로에 있는 static 폴더를 확인하세요. 이 폴더에는 Capacitor이 네이티브 앱에 포함할 모든 정적 파일이 있습니다.

__CAPGO_KEEP_0__를 프로젝트에 추가하는 방법

  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

__CAPGO_KEEP_0__를 프로젝트에 추가하는 방법

  • @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

Replace my-app with your app name and com.example.myapp with your app ID (reverse domain notation).

  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. 자연어 플랫폼 폴더를 추가하세요:
bunx cap add ios
bunx cap add android

Capacitor은 프로젝트의 루트 폴더에 자연어 프로젝트를 포함하는 폴더를 생성하고, ios 그리고 android 폴더를 생성합니다.

Android 프로젝트를 빌드하려면 Android Studio가 필요합니다. iOS를 위해 Mac와 Xcode가 필요합니다.프로젝트를 빌드하고 동기화하세요: 프로젝트를 빌드하고 동기화하세요:.

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

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

네이티브 앱 빌드 및 배포

네이티브 모바일 앱을 빌드하고 배포하려면 다음 단계를 따르십시오: iOS 앱을 개발하려면 Xcode가 설치되어 있어야 하며, Android 앱을 개발하려면 Android Studio가 설치되어 있어야 합니다. 또한 앱 스토어에 앱을 배포하려면 iOS에서는 Apple Developer Program에 등록하고 Android에서는 Google Play Console에 등록해야 합니다. Xcode Android Studio 네이티브 프로젝트를 열어보십시오: iOS:

  1. Android:

또는 직접 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__을 열어보십시오:

bun run mobile:ios

앱을 빌드하고 실행하십시오:

bun run mobile:android

Or directly with Capacitor CLI:

bunx cap open ios
bunx cap open android
  1. Android Studio

android-studio-run

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

  • Xcode에서 실제 장치에 앱을 배포하기 위해 서명 계정을 설정하십시오. 이 과정을 처음으로 진행하는 경우, Xcode는 Apple Developer Program에 등록되어야 한다는 것을 알려주며, 설정이 완료되면 “Play” 버튼을 클릭하여 연결된 장치에서 앱을 실행하십시오.

Congratulations!

Next.js 웹 앱을 모바일 장치에 성공적으로 배포했습니다.
nextjs-mobile-app

Capacitor Live Reload

__CAPGO_KEEP_0__ Live Reload

  1. 개발 중에는 즉시 모바일 장치에서 변경 사항을 확인할 수 있는 Live Reload 기능을 사용할 수 있습니다. 이 기능을 활성화하려면 다음 단계를 따르십시오.

  • IP 주소를 찾으십시오.

    ipconfig getifaddr en0

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

    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 로컬 IP 주소 (예: 192.168.1.100).

  1. 원시 프로젝트에 변경 사항을 적용하세요:
bunx cap copy

명령어는 웹 폴더와 구성 변경 사항을 원시 프로젝트로 복사하지만 전체 프로젝트를 업데이트하지 않습니다. copy Android Studio 또는 Xcode를 사용하여 기기에서 앱을 다시 빌드하고 실행하세요.

  1. Next.js 앱에 변경 사항을 만들면 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.

주의: 새로운 플러그인을 설치하거나 원시 파일을 변경하면 다시 빌드해야 하는데, 라이브 리로딩은 웹 변경 사항만 적용됩니다.

Using code Plugins

Capacitor 플러그인을 사용합니다.

Capacitor 플러그인은 Next.js 앱에서 네이티브 디바이스 기능에 접근할 수 있도록 합니다. 예를 들어 Share 플러그인을 사용하는 방법에 대해 살펴보겠습니다. Share 플러그인을 사용하는 방법에 대해 살펴보겠습니다. Share 플러그인을 설치하려면 다음 명령어를 실행하세요.

  1. __CAPGO_KEEP_0__ 파일을 Share 플러그인을 사용하는 방법으로 업데이트하세요.
bun add @capacitor/share
  1. Sync 명령어를 실행하여 네이티브 프로젝트와 동기화하세요. pages/index.js Share 플러그인을 설치한 후에 새로운 플러그인을 설치할 때는 Sync 명령어를 실행하고 앱을 다시 배포해야 합니다. Sync 명령어를 실행하려면 다음 명령어를 실행하세요.
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. Sync 명령어만 실행하세요.

앱을 다시 빌드하고 디바이스에 배포하세요.

bun run mobile

Share 플러그인을 사용하면 “공유하기!” 버튼을 클릭했을 때 네이티브 공유 대화상자를 열 수 있습니다. 이 대화상자를 통해 다른 앱과 콘텐츠를 공유할 수 있습니다.

bunx cap sync
  1. next-__CAPGO_KEEP_0__-share 플러그인을 사용하세요.

__CAPGO_KEEP_0__ 플러그인은 Next.js 앱에서 네이티브 디바이스 기능에 접근할 수 있도록 합니다. 예를 들어 Share 플러그인을 사용하는 방법에 대해 살펴보겠습니다.

next-capacitor-share

To make the button look more mobile-friendly, we can add some styling using my favorite UI component library for web apps - Next.js (no pun intended).

Konsta UI v5을 Tailwind CSS 4와 함께 추가합니다.

__CAPGO_KEEP_0__년 동안 Ionic 을 사용하여 awesome cross platform applications을 빌드하고 그것은 몇 년 동안 최고의 선택이었습니다. 하지만 이제는 더 이상 추천하지 않습니다. 그것은 Next.js와 통합하기 매우 복잡하고 그것은 이미.

Tailwind CSS 4

가 있으면 그것이 가치가 없습니다. iOS와 Android에 특화된 스타일링을 가진 정말 멋진 모바일 UI를 원한다면 Konsta UI v5을 추천합니다. __CAPGO_KEEP_0__에 Tailwind CSS 4가 이미 설치되어 있어야 합니다. Next.js 앱의 모바일 UI를 향상시키기 위해 Konsta UI v5, iOS와 Android 스타일링에 적응하는 모바일 친화적인 UI 컴포넌트 라이브러리를 사용할 수 있습니다. Konsta UI v5을 통합하기 위한 단계를 따르세요.

  1. Capgo의 필요한 패키지를 설치하세요 (Konsta UI v5):
bun add konsta
  1. __CAPGO_KEEP_0__을 주 소 CSS 파일 (예를 들어, main.css)에서 Konsta UI 테마를 임포트하세요. styles/globals.css):
@import 'tailwindcss';
/* import Konsta UI v5 theme */
@import 'konsta/theme.css';
  1. Next.js (PostCSS)에서 Tailwind CSS 4를 구성하세요:

프로젝트 루트에 postcss.config.mjs Tailwind v4는 Next.js에서 직접 PostCSS를 사용합니다. 전역 임포트는 위에 이미 추가했습니다.

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Konsta UI v5 styles/globals.css component를

  1. 예시 페이지 App 모든 설정이 완료되면, Next.js 페이지에서 Konsta UI v5 React 컴포넌트를 사용할 수 있습니다. pages/_app.js:
import { App } from 'konsta/react';
import '../styles/globals.css';

function MyApp({ Component, pageProps }) {
  return (
    <App theme="ios">
      <Component {...pageProps} />
    </App>
  );
}

export default MyApp;

Capgo를 업데이트하세요.

Install the required packages (Konsta UI v5):

  1. Import Konsta UI theme in your main CSS file (e.g., pages/index.js Konsta UI v5 컴포넌트를 사용할 파일을 선택하세요:
import {
  Page,
  Navbar,
  Block,
  Button,
  List,
  ListItem,
  BlockTitle,
} from 'konsta/react';

export default function Home() {
  return (
    <Page>
      <Navbar title="My App" />

      <Block strong>
        <p>
          Here is your Next.js & Konsta UI app. Let's see what we have here.
        </p>
      </Block>
      <BlockTitle>Navigation</BlockTitle>
      <List>
        <ListItem href="/about/" title="About" />
        <ListItem href="/form/" title="Form" />
      </List>

      <Block strong className="flex space-x-4">
        <Button>Button 1</Button>
        <Button>Button 2</Button>
      </Block>
    </Page>
  );
}
  1. Material Design 테마를 위해 Konsta UI v5에 Roboto 폰트를 추가하세요 (필수):

다음과 같이 pages/_document.js main HTML 파일

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,500;0,700;1,400;1,500;1,700&display=swap"
  rel="stylesheet"
/>
  1. or

다음과 같이

main HTML 파일

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

  • 개발 서버를 다시 시작하고 앱을 재빌드하세요.
  • Next.js 앱은 이제 Konsta UI v5와 Tailwind CSS 4로 스타일링된 네이티브 모바일 UI를 지원해야 합니다.
  • Next.js 앱의 최적 성능을 보장하기 위해 다음 최적화 방법을 고려하세요:
  • 앱 크기를 최소화하기 위해 사용되지 않는 의존성과 자산을 제거하세요.
  • Leverage Capacitor’s built-in optimizations, such as web view caching and app bundling.

결론

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

성공적으로 달성한 것:

  • Next.js를 정적 내보내기 위해 구성
  • Capacitor 8을 포함하여 필수 플러그인을 추가
  • iOS 및 Android 시뮬레이터에 빌드 및 배포
  • 개발 중에 라이브 리로드를 활성화
  • 옵션으로 Konsta UI를 추가하여 네이티브 보기에 적합한 컴포넌트

다음 단계:

  • 설정 Capgo 앱 스토어 재제출 없이 오버 더 에어 업데이트
  • 카메라, 위치 정보, 푸시 알림과 같은 더 많은 네이티브 플러그인을 추가하세요
  • 프로덕션을 위해 앱 아이콘과 스플래시 화면을 구성하세요
  • 앱 스토어와 구글 플레이 제출을 위해 앱을 준비하세요

새로운 프로젝트를 시작하려면 확인하세요 Next.js 모바일 앱을 처음부터 구축하는 방법 안내서를 따라가세요.

자원

Capgo을 사용하여 더 나은 앱을 더 빠르게 개발하는 방법을 알아보세요. 무료 계정으로 가입하세요. 오늘.

Capacitor 앱에 대한 실시간 업데이트

웹层 버그가 활성화된 경우 Capgo를 통해 앱 스토어 승인까지 며칠 기다리지 않고 버그를 수정할 수 있습니다. 사용자는 배경에서 업데이트를 받으면서 네이티브 변경 사항은 일반적인 검토 경로에 남아 있습니다.

시작하기

최신 블로그 글

Capgo은 전문적인 모바일 앱을 만들기 위해 필요한 최고의洞察력을 제공합니다.

Capacitor 앱에서 2방향 통신
개발, 모바일, 업데이트
2025년 4월 26일

Capacitor 앱에서 2방향 통신

__CAPGO_KEEP_0__ 앱에서 5가지 OTA 업데이트 실수를 피하는 방법
개발, 보안, 업데이트
2025년 4월 13일

__CAPGO_KEEP_0__ 앱에서 5가지 OTA 업데이트 실수를 피하는 방법

5 모바일 앱 실시간 업데이트 보안 최적화 방법
개발, 모바일, 업데이트
2025년 1월 14일

5 모바일 앱 실시간 업데이트 보안 최적화 방법

블로그에서 모두 보기