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

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

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

마틴 도나디유

Martin Donadieu

컨텐츠 마케터
Next.js 모바일 앱을 처음부터 만들기: Capacitor 8

소개

Next.js로 모바일 앱을 처음부터 만들고 싶으신가요? 이 가이드에서는 모바일을 위한 새로운 Next.js 15 프로젝트를 만들고, 그 프로젝트를 Native iOS 및 Android 앱으로 패키징하는 방법을 알려드립니다. Capacitor 8.

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

필요 시간: ~30분

만들어질 내용:

  • App Router를 사용하는 새로운 Next.js 15 프로젝트
  • 정적 내보내기 구성 설정: 모바일
  • 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 개발을 위해)

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

새로운 Next.js 15 프로젝트를 시작하려면:

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

다음 옵션을 선택하십시오:

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

Navigate to your project:

cd my-mobile-app

Step 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' — Node.js 서버가 필요하지 않도록 정적 HTML을 생성합니다.
  • images: { unoptimized: true } — 서버가 필요합니다. Next.js 이미지 최적화를 비활성화합니다.
  • trailingSlash: true — 네이티브 WebView에서 올바른 라우팅을 보장합니다.

Step 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

정적 파일이 포함된 디렉토리를 볼 수 있습니다. out Step 4: __CAPGO_KEEP_0__ 8 설치

Capacitor 핵심 패키지를 설치합니다.

Capacitor 핵심 패키지를 설치합니다.

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

__CAPGO_KEEP_0__의 필수 플러그인을 설치합니다. 대부분의 모바일 앱이 필요합니다.

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

이러한 플러그인이 무엇을 하는지 설명합니다.

  • @capacitor/app 앱 생명주기 이벤트 (전면/후면, 깊은 링크)
  • @capacitor/keyboard 키보드 동작 제어
  • @capacitor/splash-screen 자연스러운 스플래시 스크린 제어
  • @capacitor/status-bar 디바이스 상태바 스타일링
  • @capacitor/preferences 키-값 저장소 (localStorage와 유사한 네이티브 저장소)

5단계: Capacitor 초기화

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

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

Replace: __CAPGO_KEEP_0__

  • "My Mobile App" __CAPGO_KEEP_1__을 앱의 표시 이름으로 바꿔주세요
  • com.example.mymobileapp __CAPGO_KEEP_2__ (역방향 도메인 표기법)

이것은 __CAPGO_KEEP_0__을 생성합니다. capacitor.config.ts플러그인 구성으로 __CAPGO_KEEP_0__을 업데이트하세요:

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;

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

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

bun add @capacitor/ios @capacitor/android

네이티브 프로젝트를 생성하세요:

bunx cap add ios
bunx cap add android

이것은 __CAPGO_KEEP_0__과 __CAPGO_KEEP_1__을 생성합니다. ios __CAPGO_KEEP_2__과 __CAPGO_KEEP_3__ android __CAPGO_KEEP_2__과 __CAPGO_KEEP_3__

7단계: 빌드 및 실행

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

bun run mobile

iOS 시뮬레이터에서 열기:

bun run mobile:ios

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

bun run mobile:android

Xcode (iOS)에서:

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

Android Studio에서:

  1. Gradle이 동기화 완료될 때까지 기다리세요
  2. __CAPGO_KEEP_0__에서 디바이스 드롭다운에서 에뮬레이터를 선택하세요
  3. __CAPGO_KEEP_1__ 버튼을 클릭하거나 __CAPGO_KEEP_2__를 누르세요 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의 편집을 장치에서 실시간으로 반영됩니다.

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

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

11단계: 안전 영역 처리

모바일 기기는 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 설정
  • 딥 링크: 앱 URL 스키마를 구성하세요

추가 기능 추가

  • 카메라: bun add @capacitor/camera
  • 위치 정보: bun add @capacitor/geolocation
  • 푸시 알림: bun add @capacitor/push-notifications
  • 파일 시스템: bun add @capacitor/filesystem

UI 향상

Consider adding Konsta UI iOS/Android 컴포넌트에 원생 iOS/Android 컴포넌트를 위해:

bun add konsta

오버 더 에어 업데이트

__CAPGO_KEEP_0__ Capgo __CAPGO_KEEP_0__

bunx @capgo/cli init

문제 해결

“Cannot find module”이라는 오류로 빌드가 실패합니다. 실행 bun install 다시 시도해 보세요.

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

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

장치에 변경 사항이 보이지 않습니다 변경 사항이 적용된 후에 bun run mobile 장치에 변경 사항이 보이지 않으면, 변경 사항이 실제로 적용되었는지 확인하고, IP 주소가 정확하고 개발 서버가 실행 중인지 확인하세요.

자원

앱을 배달하기 위해 준비되셨나요? Capgo이 업데이트를 더 빠르게 전달하는 데 어떻게 도움이 될 수 있는지 알아보세요 — 무료 계정으로 가입하세요 오늘.

실시간으로 Capacitor 앱에 업데이트

웹-layer 버그가 실시간으로 실행 중일 때, 앱 스토어 승인 대기 없이 Capgo를 통해 수정을 배포하세요. 사용자는 배경에서 업데이트 받으며, 네이티브 변경 사항은 일반적인 검토 경로를 유지합니다.

시작하기

최신 블로그 글

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

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

Capacitor 앱에서 2방향 통신

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

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

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

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

블로그에서 모두 보기