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

소개

Next.js로 모바일 앱을 처음부터 구축하고 싶으십니까? 이 안내서에서는 모바일을 위해 처음부터 설정된 Next.js 15 프로젝트를 생성하는 방법을 안내합니다. 그리고 그 프로젝트를 Native iOS 및 Android 앱으로 패키징하는 방법을 알려드립니다. Capacitor 8.

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

소요 시간: ~30분

생성할 내용:

• Next.js 15 프로젝트
• 모바일용 정적 내보내기 구성
• Capacitor 8
• Native iOS 및 Android 앱
• 라이브 리로드 개발 환경

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

사전 요구 사항

다음 설치가 필요합니다.

• Node.js 18+ (__CAPGO_KEEP_0__ node --version)
• Bun Xcodecurl -fsSL https://bun.sh/install | bash)
• (macOS 전용, iOS 개발을 위해) Android Studio
• Android Studio (for Android 개발)

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

Next.js 15 프로젝트를 새로 만들기 시작하세요:

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

입력받을 때 다음 옵션을 선택하세요:

• TypeScript: Yes (권장)
• ESLint: Yes
• Tailwind CSS: Yes (모바일 스타일링을 위해 권장)
• src/ 디렉토리: 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 Image Optimization을 비활성화합니다 (서버가 필요합니다).
• 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 static 파일이 포함된 디렉토리를 볼 수 있습니다.

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/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

대체:

• "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;

Step 6: 네이티브 플랫폼 추가

플랫폼 패키지 설치:

bun add @capacitor/ios @capacitor/android

네이티브 프로젝트 생성:

bunx cap add ios
bunx cap add android

이것은 생성합니다. ios 그리고 android 네이티브 프로젝트가 포함된 디렉터리입니다.

Step 7: 빌드 및 실행

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

bun run mobile

iOS 시뮬레이터에서 열기:

bun run mobile:ios

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

bun run mobile:android

Xcode (iOS)에서:

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

Android Studio에서:

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

8단계: Live Reload 설정

개발을 위해 더 빠르게 하려면, 변경 사항이 즉시 장치에 나타나도록 Live Reload를 활성화하세요.

1. 로컬 IP 주소를 찾으세요:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

2. 개발 Capacitor 설정을 생성하세요. Add to 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;

3. 개발 서버를 시작하고 config를 네이티브로 복사하세요:

bun run dev &
NODE_ENV=development bunx cap copy

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

code의 Next.js 편집 사항은 이제 기기에서热 재로드됩니다.

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 및 전환

Capgo 플러그인을 사용하여 Konsta UI 대신 자연스러운 모바일 느낌을 얻으세요:

• @capgo/capacitor-자연스러운-네비게이션 — Liquid Glass 탭바와 자연스러운 네비게이션바
• @capgo/capacitor-전환 — 자연스러운 느낌의 페이지 전환

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

Tailwind safe areas를 위해 추가하세요 @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

__CAPGO_KEEP_2__ __CAPGO_KEEP_2__ @capgo/capacitor-자연스러운-네비게이션을 사용하세요, __CAPGO_KEEP_2__ @capgo/capacitor-전환을 사용하세요와 함께 tailwind-capacitor 저장소 Next.js에 대한 특정 설정을 위해

iOS 레이아웃 문제를 해결하는 방법 (뷰포트, 안전 영역, 가로 스크롤)

iOS에서 콘텐츠가 잘려나거나-shifted 또는 가로 스크롤 가능한 경우 overflow-x: hidden iOS에서 콘텐츠가 잘려나거나-shifted 또는 가로 스크롤 가능한 경우를 해결하려면

뷰포트 메타 태그가 올바르게 적용되었는지 확인하세요

App Router (app/Pages Router에서 viewport export app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

from (pages/put the viewport meta tag in pages/_app.tsx, not _document.tsx.

iOS 안전 영역을 하나의 루트 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, utilities처럼 패딩을 표현할 수 있습니다. pt-safe pb-safe px-safe 그것을 단일 셸에 적용하세요.

Capacitor iOS contentInset 를 never 첫 번째로

In __CAPGO_KEEP_0__에서 Native Navigation의 CSS (또는 Native Navigation의)가 Safe Area를 제어하도록 하세요. capacitor.config.ts__CAPGO_KEEP_0__의 자동 콘텐츠 인셋과 CSS의 패딩을 혼합하는 것은 일반적인 더블 스페이싱의 원인입니다. contentInsetMode: 'css'실제로 넘치는 요소를 찾으세요.

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Safari Web Inspector에서 실행하세요:

Tailwind의 경우 __CAPGO_KEEP_0__를 __CAPGO_KEEP_0__로 대체하세요.

__CAPGO_KEEP_0__를 __CAPGO_KEEP_0__로 대체하세요. 100vw__CAPGO_KEEP_0__를 __CAPGO_KEEP_0__로 대체하세요. w-screen__CAPGO_KEEP_0__를 __CAPGO_KEEP_0__로 대체하세요. min-width.

__CAPGO_KEEP_0__를 __CAPGO_KEEP_0__로 대체하세요.

[...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,
  }));

__CAPGO_KEEP_0__를 __CAPGO_KEEP_0__로 대체하세요. w-screen __CAPGO_KEEP_0__를 __CAPGO_KEEP_0__로 대체하세요. w-full __CAPGO_KEEP_0__ 100vw / w-screen가능한 경우 많은 수평 방출 문제는

Over-the-Air Updates

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

bunx @capgo/cli init

문제 해결

빌드가 "Cannot find module"로 실패합니다. 실행 bun install 다시 시도해 보세요.

iOS: "No signing identity found" Xcode를 열고 Signing & Capabilities로 이동하여 개발 팀을 선택하세요.

안드로이드: “SDK 위치를 찾을 수 없음” 생성 android/local.properties 와 sdk.dir=/path/to/android/sdk

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

__CAPGO_KEEP_0__ 8 문서

• Capacitor 8 Documentation
• __CAPGO_KEEP_0__ - 라이브 업데이트
• @Capgo/__CAPGO_KEEP_1__-native-navigation
• @capgo/capacitor-transitions
• @capgo/capacitor-transitions
• @capgo/tailwind-capacitor

앱을 배포할 준비가 되셨나요? Capgo이 업데이트를 더 빠르게 전달하는 방법에 대해 알아보세요 — __CAPGO_KEEP_0__ 무료 계정으로 가입하세요 오늘.

Capacitor으로부터 Build a Next.js Mobile App from Scratch with Capacitor 8

__CAPGO_KEEP_0__을 사용하고 있다면 Build a Next.js Mobile App from Scratch with Capacitor 8 CI/CD 자동화 계획을 세우려면 __CAPGO_KEEP_0__ CI/CD와 연결하세요 Capgo CI/CD Capgo CI/CD에서 제품 워크플로우를 관리하세요 Capgo Native Builds Capgo Native Builds에서 제품 워크플로우를 관리하세요 Capgo 통합 Capgo 통합을 위한 제품 워크플로우 CI/CD 통합 CI/CD 통합 구현 세부 정보를 위한 GitHub 액션 통합 GitHub 액션 통합 구현 세부 정보를 위한