Capacitor 8을 사용하여 Next.js 모바일 앱부터 시작하기

소개

Next.js를 사용하여 모바일 앱을 처음부터 만들고 싶으신가요? 이 가이드에서는 모바일을 위해 일부터 일까지 Next.js 15 프로젝트를 구성하고 __CAPGO_KEEP_0__ 8을 사용하여 iOS 및 Android 앱으로 패키징하는 방법을 안내합니다. Capacitor 8.

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

시간 소요량: ~30분

gì가 만들 것인가:

새로운 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

(입력받을 때) 다음 옵션을 선택하세요.

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

프로젝트로 이동:

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' — 정적 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: 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 그리고 네이티브 프로젝트가 포함된 디렉터리. android Step 7: Build and Run

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

iOS 시뮬레이터에서 열기:

bun run mobile

또는 Android 에뮬레이터:

bun run mobile:ios

Xcode (iOS)에서:

bun run mobile:android

디바이스 드롭다운에서 시뮬레이터를 선택하세요

Play 버튼을 클릭하거나
Android Studio에서: Cmd + R

Gradle이 동기화가 완료될 때까지 기다리세요

디바이스 드롭다운에서 에뮬레이터를 선택하세요
Step 7: Build and Run
Click the Run button or press Shift + F10

Step 8: Set Up Live Reload

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

장치의 IP 주소를 찾으세요:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

개발 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;

개발 서버를 시작하고 네이티브에 설정을 복사하세요.

bun run dev &
NODE_ENV=development bunx cap copy

Xcode/Android Studio에서 다시 빌드하세요.

이제 Next.js code의 편집을 장치에 즉시 반영할 수 있습니다.

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;
}

프로젝트 구조

Your project should now look like this:

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
└── ...

다음 단계

You now have a working Next.js mobile app. Here’s what to do next:

필수 설정

App Icons: Replace default icons in ios/App/App/Assets.xcassets and android/app/src/main/res
Splash Screen: Customize in native projects or use @capacitor/splash-screen config
깊이 링크: 앱의 URL 스키마를 구성하십시오

더 많은 기능 추가

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

자연스러운 UI 및 전환

Liquid Glass 탭바와 네이티브 네비게이션을 사용하여 Capgo 플러그인 대신 __CAPGO_KEEP_1__-native-navigation을 사용하십시오.

@capgo/capacitor-native-navigation — Liquid Glass 탭바와 네이티브 네비게이션
@capgo/capacitor-transitions — 원생느낌의 페이지 전환

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

Tailwind의 safe area를 추가하려면 @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

See @capgo/capacitor-native-navigation을 사용하는 방법, @capgo/capacitor-transitions을 사용하는 방법, 그리고 tailwind-capacitor 리포지토리 Next.js에 대한 특정 설정을위한

iOS 레이아웃 문제 (뷰포트, Safe Area, 및 수평적 오버플로우)를 해결하는 방법

iOS에서 콘텐츠가 잘려나거나-shifted, 또는 수평적으로 스크롤할 수 있다면, 뷰포트 태그를 수정하거나 더 추가하는 것만으로는 문제를 해결할 수 없다. 이 체크를 순서대로 진행하십시오. overflow-x: hidden __CAPGO_KEEP_0__

viewport meta 태그가 올바르게 적용되었는지 확인하세요.

App Router (app/): export 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, not _document.tsx.

iOS safe area를 하나의 루트 wrapper에서만 처리하세요.

싱글 앱 셸을 생성하고 안전 영역 패딩을 거기에 적용하세요 — 여러 중첩된 컴포넌트에서 여러 번 적용하지 마세요.

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);
}

모든 페이지 콘텐츠를 내부에 넣어주세요. .app-shell. 중복된 안전 영역 패딩이 헤더, 모달, 레이아웃 wrapper에 적용되면 UI가 잘린 것처럼 보이거나 너무 크게 보입니다.

위치 @capgo/tailwind-capacitor, 사용자 지정 패딩을 표현할 수 있는 유틸리티들처럼 pt-safe pb-safe px-safe 단일 터미널에서

Capacitor iOS `contentInset` 를 `never` 첫 번째

In capacitor.config.ts, 원하는 경우 Native Navigation의 contentInsetMode: 'css'안전 영역을 CSS (또는 Native Navigation)가 관리하도록 하세요.

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

Capacitor의 자동 콘텐츠 인셋과 CSS 패딩을 혼합하는 것은 env(safe-area-inset-*) 일반적인 오버플로우 원인입니다.

실제로 오버플로우가 발생하는 요소를 찾으세요.

일반적으로 원인은 사용하는 100vw, Tailwind w-screen, 고정 픽셀 너비, 또는 큰 min-width.

Safari Web Inspector에서 실행:

[...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 가능한 경우. 많은 수평 방출 문제는 100vw / w-screen, 중복된 safe-area 패딩, 또는 고정 너비 컨테이너 — viewport meta 태그 자체가 아니라.

Over-the-Air 업데이트

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

bunx @capgo/cli init

[Troubleshooting]

[Build fails with “Cannot find module”] Run bun install and try again.

[iOS: “No signing identity found”] Open Xcode, go to Signing & Capabilities, and select your development team.

[Android: “SDK location not found”] Create android/local.properties with sdk.dir=/path/to/android/sdk

[Changes not appearing on device] [Make sure you ran bun run mobile after making changes. For live reload, verify the IP address is correct and the dev server is running.]

자원

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

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

__CAPGO_KEEP_0__을 사용 중이시면 Next.js 모바일 앱을 Capacitor 8부터 scratch로 만들기 CI/CD 자동화 계획을 만들기 위해 __CAPGO_KEEP_0__와 연결하세요. Capgo CI/CD Capgo CI/CD에서 제품 워크플로우를 위해 Capgo 네이티브 빌드 Capgo 네이티브 빌드에서 제품 워크플로우를 위해 Capgo 통합 Capgo 통합에서 제품 워크플로우를 위해 CI/CD 통합 CI/CD 통합 구현 세부 사항을 위해 GitHub 액션 통합 GitHub 액션 통합 구현 세부 사항을 위해

Capacitor 8을 사용하여 스캔부터 시작하는 모바일 개발을 위한 Next.js 모바일 앱을 만드는 방법

소개