메인 콘텐츠로 건너뛰기
Capgo 로고
튜토리얼

Capacitor을 이용한 Nuxt 모바일 앱 만들기

단계별 가이드로 Nuxt 4 프로젝트를 생성하고 Capacitor 8을 사용하여 iOS 및 Android 모바일 앱으로 변환하는 방법을 설명합니다. 모바일 개발을 시작하는 데 적합합니다.

작성 기여자

마틴 도나디우

작성자

발레리아

리뷰어

조던

Editor

Nuxt 모바일 앱을 처음부터 만들기 위해 Capacitor 8

소개

Nuxt로 모바일 앱을 처음부터 만들고 싶으신가요? 이 가이드에서는 Nuxt 4 프로젝트를 처음부터 모바일을 위한 설정으로 만들고, __CAPGO_KEEP_0__를 사용하여 iOS와 Android 앱으로 패키징하는 방법을 알려드립니다. Capacitor 8.

이 가이드를 따라 하시면, 시뮬레이터에서 작동하는 모바일 앱을 만들 수 있으며, 개발을 계속하고 나중에는 앱 스토어와 구글 플레이에 게시할 수 있습니다.

필요 시간: ~30분

만들어질 내용:

  • 새로운 Nuxt 4 프로젝트와 최신 디렉토리 구조
  • 모바일을 위한 정적 생성 구성
  • Capacitor 8에 필수 플러그인
  • iOS 및 Android 앱
  • 실시간 리로드 개발 환경

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

준비 사항

다음 항목이 설치되어야 합니다:

  • Node.js 18+ ( node --version)
  • Bun )curl -fsSL https://bun.sh/install | bash)
  • 패키지 매니저 ( (macOS only, for iOS development)
  • Android Studio (for Android development)

1단계: 새로운 Nuxt 4 프로젝트 만들기

Nuxt 4 프로젝트를 시작하기 위해 새로운 Nuxt 4 프로젝트를 생성하세요:

bunx nuxi@latest init my-mobile-app
cd my-mobile-app
bun install

Nuxt 4 디렉토리 구조

Nuxt 4는 앱 code이 포함된 새로운 디렉토리 구조를 사용합니다. app/ 디렉토리:

my-mobile-app/
  app/
    assets/
    components/
    composables/
    layouts/
    middleware/
    pages/
    plugins/
    utils/
    app.vue
  public/
  server/
  nuxt.config.ts
  package.json

이 구조는 앱과 서버 code 사이의 분리를 향상시킵니다.

2단계: Nuxt를 정적 생성으로 구성하기

Capacitor는 정적 HTML/JS/CSS 파일이 필요합니다. Nuxt를 정적 생성으로 구성하세요. nuxt.config.ts:

export default defineNuxtConfig({
  compatibilityDate: '2025-01-15',
  devtools: { enabled: true },

  // Enable static generation
  ssr: true,
  nitro: {
    preset: 'static',
  },
});

3단계: 모바일 스크립트 추가

업데이트 package.json 모바일 개발 스크립트와 함께

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "mobile": "bun run generate && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

정적 생성을 테스트하세요:

bun run generate

정적 파일이 포함된 .output/public 디렉토리를 볼 수 있습니다.

Step 4: Capacitor 8을 설치하세요

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

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 .output/public

대체:

  • "My Mobile App" 앱의 표시 이름으로 대체
  • com.example.mymobileapp 앱 ID (역 도메인 표기법)

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

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: '.output/public',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'dark',
    },
  },
};

export default config;

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

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

bun add @capacitor/ios @capacitor/android

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

bunx cap add ios
bunx cap add android

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

7단계: 빌드 및 실행

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

bun run mobile

iOS 시뮬레이터에서 열기:

bun run mobile:ios

또는 Android 에뮬레이터:

bun run mobile:android

In Xcode (iOS):

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

In Android Studio:

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

Step 8: Live Reload 설정

빠른 개발을 위해 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: '.output/public',
  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: '.output/public',
  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에서 다시 빌드

이제 Nuxt code의 편집을 하시면 장치에서 즉시 반영됩니다.

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

모바일 친화적인 홈 화면을 만들겠습니다. 업데이트 app/app.vue:

<template>
  <NuxtPage />
</template>

만들기 app/pages/index.vue:

<template>
  <main
    class="min-h-screen bg-linear-to-b from-green-500 to-green-700 flex flex-col items-center justify-center p-6 text-white"
  >
    <h1 class="text-4xl font-bold mb-4">My Mobile App</h1>
    <p class="text-xl mb-8 text-center opacity-90">
      Built with Nuxt 4 + Capacitor 8
    </p>

    <div v-if="appInfo" class="bg-white/20 rounded-lg p-4 backdrop-blur-sm mb-8">
      <p class="text-sm">
        {{ appInfo.name }} v{{ appInfo.version }}
      </p>
    </div>

    <div class="space-y-4 w-full max-w-sm">
      <button
        class="w-full py-4 px-6 bg-white text-green-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform"
        @click="handleGetStarted"
      >
        Get Started
      </button>
      <button
        class="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"
        @click="handleShare"
      >
        Share App
      </button>
    </div>
  </main>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { App } from '@capacitor/app';

const appInfo = ref<{ name: string; version: string } | null>(null);

let backButtonListener: { remove: () => void } | null = null;

onMounted(async () => {
  // Get app info
  try {
    appInfo.value = await App.getInfo();
  } catch (e) {
    // Web fallback
    appInfo.value = { name: 'My Mobile App', version: '1.0.0' };
  }

  // Handle Android back button
  backButtonListener = await App.addListener('backButton', ({ canGoBack }) => {
    if (!canGoBack) {
      App.exitApp();
    } else {
      window.history.back();
    }
  });
});

onUnmounted(() => {
  backButtonListener?.remove();
});

function handleGetStarted() {
  // Navigate to onboarding or main app
  console.log('Get started clicked');
}

async function handleShare() {
  // We'll implement this with the Share plugin later
  console.log('Share clicked');
}
</script>

10단계: Tailwind CSS 추가하기

스타일링이 작동하려면 프로젝트에 Tailwind CSS를 추가하세요:

bun add tailwindcss @tailwindcss/vite

업데이트 nuxt.config.ts:

import tailwindcss from '@tailwindcss/vite';

export default defineNuxtConfig({
  compatibilityDate: '2025-01-15',
  devtools: { enabled: true },

  ssr: true,
  nitro: {
    preset: 'static',
  },

  css: ['~/assets/css/main.css'],

  vite: {
    plugins: [tailwindcss()],
  },
});

만들기 app/assets/css/main.css:

@import 'tailwindcss';

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

11단계: 공유 플러그인 추가하기

공유 버튼 기능을 implement 하겠습니다:

bun add @capacitor/share

업데이트 app/pages/index.vue Share 플러그인을 사용하려면:

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { App } from '@capacitor/app';
import { Share } from '@capacitor/share';

// ... existing code ...

async function handleShare() {
  try {
    await Share.share({
      title: 'Check out this app!',
      text: 'Built with Nuxt 4 and Capacitor 8',
      url: 'https://capacitorjs.com',
      dialogTitle: 'Share with friends',
    });
  } catch (e) {
    console.log('Share cancelled or failed:', e);
  }
}
</script>

Sync 및 Rebuild:

bun run mobile

프로젝트 구조

프로젝트 구조가 다음과 같이 보이면 됩니다:

my-mobile-app/
├── android/                  # Android native project
├── ios/                      # iOS native project
├── .output/
│   └── public/              # Static build output
├── app/
│   ├── assets/
│   │   └── css/
│   │       └── main.css
│   ├── pages/
│   │   └── index.vue
│   └── app.vue
├── capacitor.config.ts       # Capacitor configuration
├── nuxt.config.ts            # Nuxt configuration
├── package.json
└── ...

다음 단계

역할: Capgo Builder / 네이티브 클라우드 빌드 제품 페이지. 위치: Capgo Builder / 네이티브 클라우드 빌드 제품 페이지. 메시지 키: native_build_builder_credit_next (네이티브 빌드 빌더 크레딧 다음)

이제 Nuxt 모바일 앱이 작동합니다. 다음 단계는 무엇입니까:

  • 필수 설정 앱 아이콘: ios/App/App/Assets.xcassets 기본 아이콘을 android/app/src/main/res
  • 역할: Capgo 마케팅 웹사이트. 위치: page trust.astro. 메시지 키: and (그리고) 스플래시 스크린: @capacitor/splash-screen 설정
  • 깊이 있는 링크: 앱의 URL 스키마를 구성하십시오

더 많은 기능을 추가하십시오

  • 카메라: bun add @capacitor/camera
  • 위치 정보: bun add @capacitor/geolocation
  • 푸시 알림: bun add @capacitor/push-notifications 또는 @capgo/capacitor-firebase-messaging @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-firebase-messaging
  • iOS와 Android에서 Firebase Cloud Messaging을 사용하십시오 bun add @capacitor/filesystem

파일 시스템:

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

참조: 네이티브 네비게이션을 사용하는 방법: @capgo/capacitor-네이티브-네비게이션, 트랜지션을 사용하는 방법: @capgo/capacitor-트랜지션, 그리고 capacitor-tailwind-capacitor 레포지토리 Nuxt 전용 설정을 위해.

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

iOS에서 콘텐츠가 잘려나거나-shifted 또는 가로 스크롤이 가능하다면, overflow-x: hidden viewport 태그를 더 추가하거나 조정하는 것만으로도 문제를 해결할 수 없다. 이러한 체크를 순서대로 진행하라.

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

In nuxt.config.ts, app.head:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        {
          name: 'viewport',
          content: 'width=device-width, initial-scale=1, viewport-fit=cover',
        },
      ],
    },
  },
});

iOS 안전 영역을 하나의 루트 wrapper에서만 처리하라.

단일 앱 셸을 생성하고 안전 영역 패딩을 거기에 적용하라 — 여러 개의 중첩된 컴포넌트에서만 적용하지 마라:

html,
body,
#__nuxt {
  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 설정 never 첫 번째

페이지 capacitor.config.tsprefer contentInsetMode: 'css'native inset을 비활성화하고 CSS (또는 Native Navigation의)

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) __CAPGO_KEEP_0__의 자동 콘텐츠 인셋과 CSS 패딩을 혼합하는 것은 더블 스페이싱의 일반적인 원인입니다.

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

일반적인 원인은 요소가 사용하는 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 다시 시도해 보세요.

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

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

디바이스에 변경 사항이 나타나지 않습니다 변경 사항이 적용되도록 다시 실행하세요. 라이브 리로드의 경우 IP 주소가 정확하고 개발 서버가 실행 중인지 확인하세요. bun run mobile __CAPGO_KEEP_0__

.output/public이 비어있거나 누락되었습니다. 정확히 설정했는지 확인하세요. nitro: { preset: 'static' } in nuxt.config.ts 및 실행 bun run generate.

자원

앱을 배달하기 위해 준비되셨나요? Capgo이 업데이트를 더 빠르게 전달하는 방법에 대해 배워보세요. __CAPGO_KEEP_0__ 오늘부터

Build a Nuxt Mobile App from Scratch with Capacitor 8

이미 사용 중이라면 Build a Nuxt Mobile App from Scratch with Capacitor 8 CI/CD 자동화 계획을 위해 Capgo CI/CD Capgo CI/CD Capgo Native Builds Capgo Native Builds Capgo Integrations Capgo Integrations CI/CD 통합 CI/CD 통합 구현 세부 사항 GitHub 액션 통합 for the implementation detail in GitHub Actions Integration.

실시간 업데이트를 위한 Capacitor 앱

웹-layer 버그가 활성화되면 Capgo을 통해修정을 배포하는 대신 앱 스토어 승인까지 며칠 기다리지 않도록합니다. 사용자는 배경에서 업데이트를 받으면서 네이티브 변경은 일반적인 검토 경로를 유지합니다.

마틴의 인간 지원

시작하기

최신 뉴스

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

2-Way Communication in Capacitor 앱
개발 모바일 +1
2025년 4월 26일

Capacitor 앱에서 2방향 통신

OTA 업데이트를 피해야 하는 5가지 일반적인 실수
개발 보안 +1
페이지/영역: 기업 제품/가격 페이지. 역할: UI 레이블. 표시되는 곳: enterprise.astro 페이지. 메시지 키 `enterprise_hero_security_label` (기업 영웅 보안 레이블).

2025년 4월 13일

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

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

모든 블로그 글 보기