메인 콘텐츠로 바로가기
Capgo 로고
__CAPGO_KEEP_0__

Capacitor 8을 사용하여 스캐치부터 시작하는 Next.js 모바일 앱을 빌드하세요.

Next.js 15 프로젝트를 새로 만들고 Capacitor 8을 사용하여 iOS 및 Android 모바일 앱으로 변환하는 단계별 가이드입니다. 모바일 개발을 시작하는 데 이상적입니다.

Martin Donadieu

Martin Donadieu

콘텐츠 마케터
Capacitor 8을 사용하여 스캐치부터 시작하는 Next.js 모바일 앱을 빌드하세요.

소개

Next.js로 모바일 앱을 처음부터 만들고 싶으십니까? 이 가이드는 모바일 개발을 처음부터 시작하는 Next.js 15 프로젝트를 만들고, __CAPGO_KEEP_0__ 8을 사용하여 iOS 및 Android 앱으로 패키징하는 방법을 안내합니다. Capacitor 8.

이 튜토리얼을 마치면 시뮬레이터에서 작동하는 모바일 앱을 만들 수 있으며, 개발을 계속하고 나중에는 앱 스토어와 구글 플레이 스토어에 게시할 수 있습니다.

시간 소요: ~30분

만들어 볼 건대:

  • Next.js 15 프로젝트에 App Router를 사용하는 새로운 프로젝트
  • 모바일용 정적 내보내기 설정
  • Capacitor 8에 필수 플러그인을 포함한
  • 자연어 iOS 및 Android 앱
  • 라이브 리로드 개발 설정

Next.js 앱이 이미 있으신가요? Next.js 앱을 모바일로 변환하는 방법 대신.

사전 요구 사항

__CAPGO_KEEP_0__를 설치했는지 확인하세요:

  • Node.js 18 이상이 설치되어야 합니다. (설치 여부를 확인하세요 node --version)
  • Bun 패키지 매니저 (curl -fsSL https://bun.sh/install | bash)
  • Xcode (macOS에서만 iOS 개발을 위해)
  • Android Studio (Android 개발을 위해)

1단계: 새로운 Next.js 프로젝트 만들기

새로운 Next.js 15 프로젝트를 생성하세요:

bunx create-next-app@latest my-mobile-app

프로세스 진행 중에 다음 옵션을 선택하세요:

  • TypeScript: Yes (recommended)
  • ESLint: Yes
  • Tailwind CSS: Yes (recommended for mobile styling)
  • src/ 폴더: Yes
  • App Router: Yes (recommended)
  • Import alias: 기본값 (@/*)

프로젝트로 이동하세요:

cd my-mobile-app

2단계: Next.js를 정적 내보내기 위해 구성하세요.

Capacitor은 정적 HTML/JS/CSS 파일이 필요합니다. Next.js를 정적 내보내기 위해 구성하려면 next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  // Ensure trailing slashes for proper routing in Capacitor
  trailingSlash: true,
};

export default nextConfig;

이러한 설정은 왜 필요한가요?

  • output: 'export' — 정적 HTML을 생성하여 Node.js 서버가 필요하지 않도록 합니다.
  • images: { unoptimized: true } — Next.js Image Optimization을 비활성화합니다 (서버가 필요합니다).
  • trailingSlash: true — 네이티브 WebView에서 올바른 라우팅을 보장합니다.

3단계: 모바일 스크립트 추가

모바일 개발 스크립트를 업데이트: 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"
  }
}

빌드 결과를 확인해야 합니다.

bun run build

Navigate to your project: is not translated as it is a protected token out __CAPGO_KEEP_0__ 폴더에 정적 파일이 있습니다.

4단계: Capacitor 8을 설치하세요.

Capacitor의 핵심 패키지를 설치하세요:

bun add @capacitor/core
bun add -D @capacitor/cli

대부분의 모바일 앱이 필요로 하는 필수 플러그인을 설치하세요:

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

이 플러그인이 하는 일은?

  • @capacitor/앱 — 앱의 생명주기 이벤트 (전경/후경, 깊이 링크)
  • @capacitor/키보드 — 키보드 동작을 제어하세요.
  • @capacitor/스플래시 스크린 — 네이티브 스크린을 제어하세요.
  • @capacitor/상태바 — 장치 상태 바 스타일링
  • @capacitor/설정 — 키-값 저장소 (localStorage와 같은 네이티브 저장소)

5단계: Capacitor 초기화

Capacitor을 프로젝트 세부 정보와 초기화하세요:

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir out

대체:

  • "My Mobile App" 앱의 표시 이름과 함께
  • com.example.mymobileapp 역 도메인 표기법의 앱 ID와 함께

이것은 capacitor.config.ts. 플러그인 구성으로 업데이트하세요:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'light',
    },
  },
};

export default config;

6단계: 네이티브 플랫폼 추가

플랫폼 패키지를 설치하세요:

bun add @capacitor/ios @capacitor/android

자연적인 프로젝트 생성: 

bunx cap add ios
bunx cap add android

이것은 ios 및 android 자연적인 프로젝트가 포함된 디렉토리를 생성합니다.

7단계: 빌드 및 실행

프로젝트를 빌드하고 네이티브 플랫폼과 동기화하세요:

bun run mobile

iOS 시뮬레이터에서 열기:

bun run mobile:ios

또는 Android 에뮬레이터에서 열기:

bun run mobile:android

Xcode (iOS)에서:

  1. 디바이스 드롭다운에서 시뮬레이터를 선택하세요
  2. Play 버튼을 클릭하거나 Cmd + R

Android Studio에서:

  1. Gradle 동기화가 완료될 때까지 기다려 주세요.
  2. 디바이스 드롭다운에서 에뮬레이터를 선택하세요.
  3. Run 버튼을 클릭하거나 Shift + F10

8 단계: 라이브 리로드 설정

빠른 개발을 위해 라이브 리로드를 활성화하여 변경 사항이 즉시 디바이스에 나타나도록 하세요.

  1. 디바이스 IP 주소를 찾으세요:
# macOS
ipconfig getifaddr en0

# Windows
ipconfig
  1. 개발 Capacitor 설정을 생성하세요. 다음을 추가하세요: capacitor.config.ts:
import type { CapacitorConfig } from '@capacitor/cli';

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... same plugin config
  },
};

const prodConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    // ... same plugin config
  },
};

const config = process.env.NODE_ENV === 'development' ? devConfig : prodConfig;

export default config;
  1. 개발 서버를 시작하고 설정을 네이티브로 복사하세요:
bun run dev &
NODE_ENV=development bunx cap copy
  1. Xcode/Android Studio에서 다시 빌드하세요.

현재 Next.js code의 편집 사항은 디바이스에서 즉시 리로드됩니다.

9 단계: 첫 번째 모바일 화면 만들기

간단한 모바일 친화적인 홈 화면을 만들겠습니다. 업데이트 src/app/page.tsx:

'use client';

import { useEffect, useState } from 'react';
import { App } from '@capacitor/app';
import { Keyboard } from '@capacitor/keyboard';

export default function Home() {
  const [appInfo, setAppInfo] = useState<{ name: string; version: string } | null>(null);

  useEffect(() => {
    // Get app info on mount
    App.getInfo().then(setAppInfo).catch(console.error);

    // Handle back button on Android
    const backHandler = App.addListener('backButton', ({ canGoBack }) => {
      if (!canGoBack) {
        App.exitApp();
      } else {
        window.history.back();
      }
    });

    // Hide keyboard when tapping outside inputs
    const keyboardHandler = Keyboard.addListener('keyboardWillShow', () => {
      document.body.classList.add('keyboard-open');
    });

    return () => {
      backHandler.then(h => h.remove());
      keyboardHandler.then(h => h.remove());
    };
  }, []);

  return (
    <main className="min-h-screen bg-linear-to-b from-blue-500 to-blue-700 flex flex-col items-center justify-center p-6 text-white">
      <h1 className="text-4xl font-bold mb-4">My Mobile App</h1>
      <p className="text-xl mb-8 text-center opacity-90">
        Built with Next.js 15 + Capacitor 8
      </p>

      {appInfo && (
        <div className="bg-white/20 rounded-lg p-4 backdrop-blur-sm">
          <p className="text-sm">
            {appInfo.name} v{appInfo.version}
          </p>
        </div>
      )}

      <div className="mt-12 space-y-4 w-full max-w-sm">
        <button className="w-full py-4 px-6 bg-white text-blue-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform">
          Get Started
        </button>
        <button className="w-full py-4 px-6 bg-white/20 text-white rounded-xl font-semibold text-lg backdrop-blur-sm active:scale-95 transition-transform">
          Learn More
        </button>
      </div>
    </main>
  );
}

10단계: 안전 영역 처리 추가

모바일 기기는 notch, 홈 인디케이터, 상태 바를 가지고 있습니다. Tailwind를 사용하여 안전 영역 처리를 추가하세요.

수정 src/app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  --sat: env(safe-area-inset-top);
  --sar: env(safe-area-inset-right);
  --sab: env(safe-area-inset-bottom);
  --sal: env(safe-area-inset-left);
}

body {
  padding-top: var(--sat);
  padding-right: var(--sar);
  padding-bottom: var(--sab);
  padding-left: var(--sal);
}

/* Prevent text selection on mobile */
* {
  -webkit-user-select: none;
  user-select: none;
  -webkit-tap-highlight-color: transparent;
}

/* Allow text selection in inputs */
input, textarea {
  -webkit-user-select: auto;
  user-select: auto;
}

/* Keyboard handling */
.keyboard-open {
  --sab: 0px;
}

프로젝트 구조

프로젝트는 다음과 같이 보이게 되어야 합니다.

my-mobile-app/
├── android/              # Android native project
├── ios/                  # iOS native project
├── out/                  # Static build output
├── src/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── ...
├── capacitor.config.ts   # Capacitor configuration
├── next.config.ts        # Next.js configuration
├── package.json
└── ...

다음 단계

이제 Next.js 모바일 앱이 작동하고 있습니다. 다음 단계를 수행하세요:

필수 설정

  • 앱 아이콘: 기본 아이콘을 ios/App/App/Assets.xcassets 스플래시 화면: android/app/src/main/res
  • Splash Screen: 자연스러운 프로젝트에서 커스터마이즈하거나 사용 @capacitor/splash-screen __CAPGO_KEEP_0__
  • 깊이 있는 링크: __CAPGO_KEEP_0__

앱에 대한 URL 스키마를 구성

  • 더 많은 기능 추가 bun add @capacitor/camera
  • 카메라: bun add @capacitor/geolocation
  • 위치 정보: bun add @capacitor/push-notifications
  • 푸시 알림: bun add @capacitor/filesystem

파일 시스템:

UI 향상 Konsta UI iOS/Android 컴포넌트를 위한 원생 iOS/Android UI: 

bun add konsta

OTA 업데이트

설정 Capgo 앱스토어 재제출 없이 업데이트를 푸시하세요:

bunx @capgo/cli init

문제 해결

빌드가 “모듈을 찾을 수 없습니다”로 실패합니다. 실행 bun install 다시 시도해 보세요.

iOS: “인증서를 찾을 수 없습니다” Xcode를 열고 Signing & Capabilities로 이동하여 개발 팀을 선택하세요.

Android: “SDK 위치를 찾을 수 없습니다” 생성 android/local.properties 으로 sdk.dir=/path/to/android/sdk

장치에 나타나지 않는 변경 사항 변경 사항이 나타나지 않으면 장치에 변경 사항이 적용되었는지 확인하세요. 라이브 리로드를 위해 IP 주소가 정확하고 개발 서버가 실행 중인지 확인하세요. bun run mobile 자원

__CAPGO_KEEP_0__ 8 문서

Ready to ship your app? Learn how Capgo can help you deliver updates faster — __CAPGO_KEEP_0__ 오늘.

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

Capgo 앱에서 웹层 버그가 활성화된 경우, 앱 스토어 승인 대기 없이 Capgo를 통해 패치를 배포하세요. 사용자는 배경에서 업데이트 받으면서 네이티브 변경 사항은 일반적인 검토 경로에 남아 있습니다.

시작하기

블로그에서 최신 뉴스

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

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

Capacitor 앱에서 2-way 통신

5 개의 OTA 업데이트 실수를 피하는 방법
개발, 보안, 업데이트
2025년 4월 13일

5 개의 OTA 업데이트 실수를 피하는 방법

모바일 앱 실시간 업데이트에 대한 5 가지 보안最佳 관행
개발, 모바일, 업데이트
2025년 1월 14일

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

블로그에서 모두 보기