Next.js 15 프로젝트를 새로 만들고 네이티브 iOS 및 Android 모바일 앱으로 변환하는 단계별 가이드입니다. 시작하기에 적합합니다...
튜토리얼

Next.js 모바일 앱을 Capacitor 8으로부터 처음부터 만들기

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

작성자 소개

마틴 도나디유

작가

발레리아

리뷰어

조던

편집자
Next.js 모바일 앱을 Capacitor 8부터 scratch로 구축하세요

소개

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 개발을 위해)

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

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

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

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

  • TypeScript: 예 (권장)
  • ESLint: 네
  • Tailwind CSS: 네 (모바일 스타일링을 위한 권장)
  • src/ 디렉토리: 네
  • 애플리케이션 라우터: 예 (권장)
  • Import alias: 기본 (@/*)

프로젝트로 이동:

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: 모바일 스크립트 추가하기

업데이트하여 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 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/app — 앱 생명주기 이벤트 (전면/후면, 깊이 링크)
  • @capacitor/키보드 — 키보드 동작을 제어합니다.
  • @capacitor/스플래시 화면 — 네이티브 스플래시 스크린을 제어합니다.
  • @capacitor/상태바 — 장치 상태 바 스타일을 제어합니다.
  • @capacitor/설정 — 키-값 저장소 (localStorage와 같은 네이티브)

5단계: Capacitor 초기화

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

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

대체:

  • "My Mobile App" __CAPGO_KEEP_0__의 표시 이름으로 대체
  • com.example.mymobileapp __CAPGO_KEEP_0__의 앱 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단계: 네이티브 플랫폼 추가

__CAPGO_KEEP_0__ 패키지를 설치하세요:

bun add @capacitor/ios @capacitor/android

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

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

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

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

Gradle이 동기화 완료되기를 기다리세요

  1. and
  2. 기기 드롭다운에서 에뮬레이터를 선택하세요
  3. 실행 버튼을 클릭하거나 Shift + F10

8단계: Live Update 설정

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

  1. 개발을 더 빠르게 하려면 Live Reload를 활성화하여 변경 사항이 즉시 기기에서 나타나도록 하세요.
# 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. 개발 __CAPGO_KEEP_0__ 설정을 생성하세요. Add to
bun run dev &
NODE_ENV=development bunx cap copy
  1. 개발 서버를 시작하고 설정을 Native로 복사하세요:

Now edits to your Next.js code will automatically reload on the device.

이제 Next.js __CAPGO_KEEP_0__의 편집 사항이 기기에서 실시간으로 반영됩니다.

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

context: Page/area: About Capgo page. Role: UI label. Seen in: page about.astro. Message key `about_how_step_label` (About How Step Label).

모바일 기기는 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
└── ...

다음 단계

다음 단계에서는 다음을 수행하세요:

필수 설정

  • 앱 아이콘: 기본 아이콘을 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 대신 네이티브 모바일 경험을 얻으십시오:

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

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

bun add -D tailwind-capacitor

See @capgo/capacitor-자연스러운 네비게이션, Using @capgo/capacitor-transitions, 그리고 Tailwind-capacitor 레포 iOS 레이아웃 문제를 해결하는 방법 (뷰포트, Safe Area, 및 수평적 오버플로우)

iOS에서 콘텐츠가 잘린 것처럼 보인다면 Shifted, 또는 수평적으로 스크롤할 수 있는 경우 더

Fixing iOS Layout Issues (Viewport, Safe Area, and Horizontal Overflow) overflow-x: hidden 또는 뷰포트 태그만 조정하는 것은 일반적으로 문제를 해결하지 못합니다. 이러한 체크를 순서대로 진행하세요.

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

애플리케이션 라우터 (app/): export viewport from app/layout.tsx:

import type { Viewport } from 'next';

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

페이지 라우터 (pages/): 뷰포트 메타 태그를 넣으세요. pages/_app.tsx, _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가 잘린 것처럼 보이거나 너무 크게 보이는 경우가 있습니다.

With @capgo/tailwind-capacitor, __CAPGO_KEEP_0__의 유용한 클래스를 사용하여 동일한 패딩을 표현할 수 있습니다. pt-safe pb-safe px-safe 단일 셸에.

Capacitor iOS contentInset to never 첫 번째

In capacitor.config.ts, CSS (또는 Native Navigation의) safe area를 소유하도록 native inset disabled를 선호합니다. contentInsetMode: 'css'__CAPGO_KEEP_0__의 자동 콘텐츠 인셋과 CSS 패딩을 혼합하는 것은 더블 스페이싱의 일반적인 원인입니다.

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

Set Capacitor iOS env(safe-area-inset-*) first

실제로 넘치는 요소를 찾으세요.

일반적으로 범인은 요소가 사용하는 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, 중복된 안전 영역 패딩 또는 고정 너비 컨테이너에서 오는 것이 아니라, viewport meta 태그 자체에서 오는 것입니다.

Over-the-Air 업데이트

설정 Capgo 업데이트를 앱스토어 재제출 없이 푸시할 수 있습니다:

bunx @capgo/cli init

문제 해결

빌드가 “모듈을 찾을 수 없음”으로 실패합니다. 실행 bun install Capgo는 Codepush와 비교하여 더 빠르고 간편한 빌드 및 설치 프로세스를 제공합니다. Codepush는 빌드 단계에서 빌드 프로세스를 중단하고 다시 시작해야 하는 번거로움을 유발합니다. 반면 Capgo는 빌드 단계에서 빌드 프로세스를 중단하지 않고 다시 시작할 수 있습니다. Codepush는 설치 단계에서 설치 프로세스를 중단하고 다시 시작해야 하는 번거로움을 유발합니다. 반면 Capgo는 설치 단계에서 설치 프로세스를 중단하지 않고 다시 시작할 수 있습니다.

다시 시도해 보세요. iOS: “인증서를 찾을 수 없음”

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

과 장치에 나타나지 않는 변경 사항 bun run mobile __CAPGO_KEEP_0__

자원

앱을 배달하기 위해 준비되셨나요? Capgo이 업데이트를 더 빠르게 전달하는 방법을 배워보세요 — 자유 계정으로 가입하세요 오늘

Build a Next.js Mobile App from Scratch with Capacitor 8

만약 당신이 Next.js 모바일 앱을 Capacitor 8부터 scratch로 구축하고 싶다면 CI/CD 자동화 계획을 만들기 위해 Capgo CI/CD 제품 워크플로우에서 Capgo CI/CD Capgo 원시 빌드 제품 워크플로우에서 Capgo Native Builds Capgo 통합솔루션 제품 워크플로우에서 Capgo Integrations CI/CD 통합 CI/CD 통합 구현 세부 사항에 대해 GitHub 액션 통합 GitHub Actions Integration을 위한 구현 세부 정보.

Capacitor 앱에 대한 즉시 업데이트

Capgo를 통해 웹-layer 버그가 활성화된 경우, 앱 스토어 승인 대기 없이修정 배포를 통해 고치세요. 사용자는 배경에서 업데이트를 받으며, 네이티브 변경은 일반적인 검토 경로를 유지합니다.

최신 뉴스

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

2방향 통신 Capacitor 앱
개발 모바일 +1
2025년 4월 26일

Capacitor 앱에서 2-Way 통신

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

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

모바일 앱 라이브 업데이트에 대한 5 가지 보안最佳 관행
개발 모바일 +1
2025년 1월 14일

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

__CAPGO_KEEP_0__의 모든 글을 보려면