메인 콘텐츠로 바로가기
Capgo 로고
튜토리얼

Capacitor 8을 사용하여 Next.js 모바일 앱을 처음부터 만들기

Capacitor 8을 사용하여 새로운 Next.js 15 프로젝트를 만들고 iOS 및 Android 모바일 앱으로 변환하는 단계별 가이드. 모바일 개발을 시작할 때부터 완벽합니다.

Martin Donadieu

Martin Donadieu

콘텐츠 마케터
Capacitor 8을 사용하여 Next.js 모바일 앱을 처음부터 만들기

소개

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

이 튜토리얼을 마치면 시뮬레이터에서 작동하는 실제 모바일 앱을 개발하고 최종적으로 앱 스토어와 구글 플레이에 게시할 수 있습니다.

시간 소요: ~30분

What you’ll build:

  • Next.js 15 App Router 프로젝트를 새로 만들 것입니다.
  • 모바일용 정적 내보내기 설정
  • Capacitor 8에 필수 플러그인을 포함합니다.
  • iOS 및 Android 네이티브 앱
  • 라이브 리로드 개발 환경

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

사전 요구 사항

다음 설치를 확인하세요.

  • Node.js 18 이상이 설치되어야 합니다. (체크해 보세요. node --version)
  • Bun 패키지 매니저 (curl -fsSL https://bun.sh/install | bash)
  • Xcode (macOS 전용, iOS 개발용)
  • Android Studio (Android 개발용)

Step 1: Next.js 프로젝트 만들기

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

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

When prompted, select these options:

  • TypeScript: Yes (권장)
  • ESLint: Yes
  • Tailwind CSS: Yes (recommended for mobile styling)
  • src/ directory: Yes
  • App Router: Yes (recommended)
  • Import alias: Default (@/*)

Navigate to your project:

cd my-mobile-app

Step 2: Capgo 설정을 위해 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에서 올바른 라우팅을 보장함

Step 3: 모바일 스크립트 추가하기

__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"
  }
}

빌드 테스트하기:

bun run build

정적 파일이 포함된 out 디렉토리를 확인하세요.

Step 4: Install Capacitor 8

Capacitor core 패키지를 설치하세요:

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 and android __CAPGO_KEEP_0__

프로젝트를 빌드하고 네이티브 플랫폼과 동기화하십시오.

프로젝트를 빌드하고 네이티브 플랫폼과 동기화하십시오.

bun run mobile

iOS 시뮬레이터에서 열기:

bun run mobile:ios

또는 안드로이드 에뮬레이터에서 열기:

bun run mobile:android

Xcode (iOS)에서:

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

Android Studio에서:

  1. Gradle 동기화가 완료될 때까지 기다리십시오.
  2. 디바이스 드롭다운에서 에뮬레이터를 선택하십시오.
  3. Click the Run button or press Shift + F10

Step 8: Set Up Live Reload

개발을 더 빠르게 하려면, 변경 사항이 즉시 장치에 나타나도록 라이브 리로드를 활성화하세요.

  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에서 다시 빌드하세요.

code의 Next.js 편집이 장치에 즉시 반영됩니다.

Step 9: Create Your First Mobile Screen

간단한 모바일 친화적인 홈 스크린을 만들겠습니다. 업데이트 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>
  );
}

Step 10: Add Safe Area Handling

모바일 장치에는 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
  • 스플래시 화면: 자연스럽게 프로젝트에서 커스터마이즈하거나 @capacitor/splash-screen config
  • Deep Links: 앱 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 컴포넌트를 위해

bun add konsta

오버 더 에어 업데이트

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

bunx @capgo/cli init

문제 해결

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

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

Android: “SDK 위치를 찾을 수 없음” 생성 android/local.properties with sdk.dir=/path/to/android/sdk

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

자원

앱을 배달하기 위해 준비되셨나요? Capgo이 업데이트를 더 빠르게 배달할 수 있도록 도와드릴 수 있습니다 — 무료 계정으로 가입하세요 오늘.

Capacitor 8으로 Build a Next.js Mobile App from Scratch를 계속 진행하세요

If you are using Capacitor 8을 사용하여 to plan CI/CD automation, connect it with Capgo CI/CD for the product workflow in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations for the product workflow in Capgo Integrations, CI/CD Integration CI/CD Integration 구현 세부 사항에 대해 GitHub Actions Integration implementation 세부 정보에 대한 GitHub 액션 통합.

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

웹-layer 버그가 활성화된 경우 Capgo를 통해修정을 배포하는 대신 앱 스토어 승인까지 며칠 기다리지 말고. 사용자는 배경에서 업데이트를 받으면서 네이티브 변경 사항은 일반적인 검토 경로에 남아있다.

시작하기

블로그에서 최신 내용

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

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

Capacitor 앱에서 2-Way Communication

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

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

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

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

블로그에서 모두 보기