메인 콘텐츠로 건너뛰기
Capgo 로고
__CAPGO_KEEP_0__

Capacitor를 사용하여 iOS & Android로 Nuxt 앱을 변환하세요.

Capacitor를 사용하여 기존의 Nuxt 4 웹 애플리케이션을 native iOS 및 Android 모바일 앱으로 변환하세요. 정적 생성을 구성하는 방법, native 플러그인을 추가하는 방법, 앱 스토어에 배포하는 방법에 대한 완전한 가이드.

Martin Donadieu

Martin Donadieu

콘텐츠 마케터
Capacitor를 사용하여 iOS & Android로 Nuxt 앱을 변환하세요.

소개

Nuxt 웹 애플리케이션이 이미 있는 경우, 이 가이드에서는 __CAPGO_KEEP_0__를 사용하여 native iOS 및 Android 모바일 앱으로 변환하는 방법을 배울 것입니다. Capacitor 8 — 성능이 향상되고 새로운 기능이 추가된 최신 버전.

Capacitor은 웹 앱을 네이티브 컨테이너에 감싸줌으로써 카메라, 파일 시스템 및 푸시 알림과 같은 장치 API에 접근할 수 있게 해주며 existing Vue 코드베이스를 유지합니다. Flutter나 React Native와 달리 anything을 다시 작성할 필요가 없습니다 — Nuxt code은 그대로 실행됩니다.

학습할 내용:

  • 기존의 Nuxt 앱을 정적 생성으로 구성합니다.
  • Capacitor 8에 필수 네이티브 플러그인을 추가하여
  • iOS 및 Android 시뮬레이터에서 빌드 및 테스트합니다.
  • 빠른 개발을 위해 라이브 리로드를 활성화합니다.
  • iOS 레이아웃 문제를 해결합니다 (뷰포트, 안전 영역, 수평 방향 오버플로우)
  • Capgo Native Navigation 및 Transitions를 사용하여 네이티브 느낌의 UI를 추가합니다.

새로운 프로젝트를 시작하고 싶으신가요? __CAPGO_KEEP_0__의 이점을 확인하세요..

Capacitor의 재사용성

  • Code의 이점을 확인하세요.: 모바일 앱과 웹 앱 간에 Vue 컴포넌트 및 로직을 공유하세요.
  • 성능: Nuxt의 정적 생성은 모바일용 최적화된 번들을 생성합니다.
  • 자연스러운 네이티브 기능: 카메라, 위치 정보, 파일 시스템과 같은 장치 기능에 접근하기 위해 Capacitor 플러그인을 사용하세요.
  • 간소화된 개발: 익숙한 Vue/Nuxt 패턴을 사용하여 네이티브 개발을 배워야 할 필요가 없습니다.

사전 조건

시작하기 전에 다음을 확인하세요.

  • Node.js 18+ 설치
  • 기존 프로젝트 Nuxt 4 응용 프로그램
  • Xcode (iOS 개발을 위해 macOS만)
  • Android Studio (Android 개발을 위해)

모바일을 위한 Nuxt 앱 구성

Nuxt 앱을 정적 생성하기 위해 첫 번째 단계는 정적 HTML/JS/CSS 파일이 필요합니다. Capacitor을 native 앱에 번들링하기 위해.

정적 생성을 위해 package.json generate 스크립트가

{
  "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"
  }
}

중요: 서버 사이드 기능(API 경로, 서버 미들웨어 등)을 사용 중이라면, 클라이언트 사이드 대체 또는 외부 API를 사용하여 리팩토링해야 합니다.

Test the static generation by running:

bun run generate

You should see a .output/public folder with your static files. This is what Capacitor will bundle into your native app.

Capacitor을 프로젝트에 추가하는 방법

Nuxt 앱을 네이티브 모바일 컨테이너로 패키징하려면 다음 단계를 따르세요.

  1. Capacitor core 및 CLI을 설치하세요.
bun add @capacitor/core
bun add -D @capacitor/cli
  1. Capacitor의 일반적인 플러그인을 설치하세요. 일반적으로 필요한 플러그인은 다음과 같습니다.
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와 같은 네이티브 키-값 스토리지
  1. 프로젝트 세부 정보와 Capacitor를 초기화하세요:
bunx cap init my-app com.example.myapp --web-dir .output/public

Replace my-app 와 com.example.myapp 와

  1. 앱 이름으로 capacitor.config.ts 앱 ID (역 도메인 표기법)로
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-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;
  1. 자연스러운 플랫폼 설치:
bun add @capacitor/ios @capacitor/android
  1. 자연스러운 플랫폼 폴더를 추가하세요:
bunx cap add ios
bunx cap add android

Capacitor은 ios 및 android 프로젝트의 루트 폴더에 있는 폴더를 생성하여 자연스러운 프로젝트를 포함합니다.

Android 프로젝트를 빌드하려면 Android Studio가 필요합니다. iOS의 경우 Xcode.

  1. 프로젝트를 빌드하고 동기화하세요:
bun run mobile

이것은 정적 Nuxt 빌드를 생성하고 자연스러운 플랫폼과 파일을 동기화하는 커스텀 스크립트를 실행합니다.

자연스러운 앱 빌드 및 배포

native 모바일 앱을 빌드하고 배포하려면 다음 단계를 따르세요:

iOS 앱을 개발하려면 Xcode 설치되어야 하며, Android 앱을 개발하려면 Android Studio 설치되어야 합니다. 또한 앱을 스토어에 배포하려면 iOS에는 Apple Developer Program에, Android에는 Google Play Console에 등록해야 합니다.

  1. native 프로젝트를 열어보세요:

iOS:

bun run mobile:ios

Android:

bun run mobile:android

또는 직접 Capacitor CLI:

bunx cap open ios
bunx cap open android
  1. 앱을 빌드하고 실행하세요:

android-studio-run

  • 안드로이드 스튜디오에서 프로젝트가 준비되기를 기다리십시오. 그 다음에 “실행” 버튼을 클릭하여 연결된 장치나 에뮬레이터에 앱을 배포하십시오.

xcode-run

  • Xcode에서 실제 장치에 앱을 배포하기 위해 서명 계정을 설정하십시오. 이 과정을 처음으로 진행하는 경우 Xcode는 Apple Developer Program에 등록되어 있어야 한다는 것을 알려주실 것입니다. 설정이 완료되면 “재생” 버튼을 클릭하여 연결된 장치에서 앱을 실행하십시오.

성공하셨습니다! Nuxt 웹 앱을 모바일 장치에 성공적으로 배포했습니다.

nuxtjs-mobile-app

그러나 개발 중에는 더 빠른 방법이 있습니다…

Capacitor Live Reload

개발 중에는 즉시 변경 사항을 모바일 장치에서 확인할 수 있는 라이브 리로드 기능을 사용할 수 있습니다. 이 기능을 활성화하려면 다음 단계를 따르십시오.

  1. 로컬 IP 주소를 찾으십시오.

  • macOS에서 터미널에서 다음 명령어를 실행하십시오.

    ipconfig getifaddr en0

  • Windows에서 다음 명령어를 실행하십시오.

    ipconfig

    출력에서 IPv4 주소를 찾으십시오.

  1. 업데이트를 capacitor.config.ts 개발 서버로 가리키도록
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: '.output/public',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... your plugin config
  },
};

export default config;

대체 YOUR_IP_ADDRESS 로컬 IP 주소 (예: 192.168.1.100).

  1. 자연스러운 프로젝트에 변경 사항을 적용하십시오:
bunx cap copy

명령어는 웹 폴더와 구성 변경 사항을 자연스러운 프로젝트로 복사하고 전체 프로젝트를 업데이트하지 않습니다. copy Xcode/Android Studio에서 Nuxt 개발 서버를 시작하고 다시 빌드하십시오:

  1. Nuxt 앱에 변경 사항을 만들면 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.
bun run dev

주의:

새로운 플러그인을 설치하거나 자연스러운 파일에 변경 사항을 만들면 웹 변경 사항만 적용되므로 자연스러운 프로젝트를 다시 빌드해야 합니다. If you install new plugins or make changes to native files, you’ll need to rebuild the native project since live reloading only applies to web code changes.

Using Capacitor Plugins

Capacitor 플러그인은 Nuxt 앱에서 네이티브 장치 기능에 접근할 수 있도록 합니다. 네이티브 장치 기능을 사용하는 방법에 대해 알아보겠습니다. 공유 플러그인 예를 들어 공유 플러그인을 사용하는 방법을 살펴보겠습니다.

  1. 공유 플러그인을 설치하세요.
bun add @capacitor/share
  1. 공유 플러그인을 사용하는 페이지를 만들거나 업데이트하세요. Nuxt 4에서는 페이지가 app/pages/:
<template>
  <div class="p-6">
    <h1 class="text-2xl font-bold mb-4">Welcome to Nuxt + Capacitor!</h1>
    <button
      @click="shareContent"
      class="px-6 py-3 bg-blue-600 text-white rounded-lg font-semibold"
    >
      Share now!
    </button>
  </div>
</template>

<script setup lang="ts">
import { Share } from '@capacitor/share';

async function shareContent() {
  await Share.share({
    title: 'Check this out!',
    text: 'Built with Nuxt and Capacitor',
    url: 'https://capacitorjs.com',
    dialogTitle: 'Share with friends',
  });
}
</script>
  1. 변경 사항을 네이티브 프로젝트와 동기화하세요.
bun run mobile

또는 재빌드 없이 동기화만 하세요.

bunx cap sync
  1. 앱을 장치에 다시 빌드하고 실행하세요.

이제 '공유하기!' 버튼을 클릭하면 네이티브 공유 대화상자가 나타납니다.

다음으로, iOS와 Android에서 네이티브-feeling UI를 만들 수 있습니다. Capgo 네이티브 네비게이션과 전환, iOS에서 발생하는 수평 스크롤이나 안전 영역이 잘려지는 문제를 해결할 수 있습니다.

네이티브-feeling UI를 만들기 위해 Capgo 네이티브 네비게이션과 전환을 사용하세요.

네이티브-feeling UI를 만들기 위해 __CAPGO_KEEP_0__ 네이티브 네비게이션과 전환을 사용하세요. Ionic Nuxt를 사용하여 크로스 플랫폼 애플리케이션을 빌드하는 데는 도움이 되지만 Nuxt와 통합하는 것은 이미 가지고 있는 경우에만 가치가 있는 hacky입니다. Tailwind CSS.

Nuxt + Capacitor 앱에서 원시 모바일 느낌을 위해 웹 전용 UI 키트인 Konsta UI와 같은 대신 Capgo 플러그인을 사용하십시오.

  • @capgo/capacitor-native-navigation — 원시 네비게이션 바, iOS에서 Liquid Glass 탭 바, Android에서 흐린 탭 바 스타일. Nuxt 라우터는 경로 상태를 유지하고 플러그인은 원시 창을 소유합니다.
  • @capgo/capacitor-transitions — Ionic 스타일의 페이지 전환 및 iOS 에지 스와이프 백(WebView layer)으로 WebView layer에서 iOS 에지 스와이프 백을 사용하지 않고 Ionic UI를 채택하지 않습니다.

설치 BOTH:

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

CSS inset 모드에서 원시 네비게이션 바와 웹 콘텐츠를 위한 네비게이션 바를 구성하십시오.

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Liquid Glass 탭 바를 렌더링하십시오 (iOS는 시스템 소유 렌더링을 사용하고 Android는 흐린 WebView 백그라운드 사용):

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  router.push(`/${id}`);
});

앱 셸에서 원시 페이지 전환을 추가하십시오:

<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';

initTransitions({ platform: 'auto' });

const router = useRouter();
const outletRef = ref(null);

onMounted(() => {
  if (outletRef.value) {
    setupRouterOutlet(outletRef.value, { platform: 'auto', swipeGesture: 'auto' });
  }
});

const openSettings = () => {
  setDirection('forward');
  router.push('/settings');
};
</script>

<template>
  <cap-router-outlet ref="outletRef">
    <router-view />
  </cap-router-outlet>
</template>

Wrap routed pages in cap-router-outlet, cap-page, 그리고 cap-content, 그리고 setDirection('forward') , 그리고 setDirection('back') 또는

native navigation이 소유한 웹 헤더 또는 푸터를 중복하지 않도록 하십시오. Using @capgo/capacitor-native-navigation Capacitor-native-navigation Using @capgo/capacitor-transitions.

Capacitor-transitions

Tailwind에서 안전한 영역 @capgo/tailwind-capacitor (publiched as tailwind-capacitor npm에서 발행됨). 이 프로젝트는 safe-areas Capacitor-친화적인 Tailwind 플러그인을 포함하여

bun add -D tailwind-capacitor

In app/assets/css/main.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Nuxt 4와 Tailwind CSS 4를 사용하는 경우, CSS 파일에서 이 import를 유지하세요. nuxt.config.ts.

Tailwind CSS의 pt-safe, pb-safe, px-safe 대신 env(safe-area-inset-*) 수동으로 open a PR on GitHub.

__CAPGO_KEEP_0__에서 PR을 열어주세요.

iOS 레이아웃 문제 해결 (뷰포트, 안전 영역, 가로 스크롤) overflow-x: hidden viewport 태그만 수정하거나 조정하는 경우 일반적으로 문제를 해결하지 못합니다. 이러한 확인 과정을 순서대로 진행하세요.

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

또는 nuxt.config.tsiOS safe area를 처리하기 위해 단일 루트 wrapper만 사용하세요. app.head:

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

싱글 앱 셸을 생성하고 safe area 패딩을 거기에 적용하세요 — 여러 중첩된 컴포넌트에 적용하지 마세요:

모든 페이지 콘텐츠를

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에 중복된 safe-area 패딩이 적용되어 있는 경우 UI가 잘려나거나 너무 크게 보이는 문제가 발생합니다.

그리고 @capgo/tailwind-capacitor와 같은 유틸리티를 사용하여 동일한 패딩을 표현할 수 있습니다. pt-safe pb-safe px-safe 그것만으로도 충분합니다.

iOS Capacitor 설정 contentInset __CAPGO_KEEP_0__을 never 첫 번째

In capacitor.config.ts, native inset이 disabled된 경우 CSS (또는 Native Navigation의 contentInsetMode: 'css')가 safe area를 관리하도록 하세요.

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

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

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

일반적인 원인은 Tailwind 100vw, 고정 픽셀 너비를 사용하는 요소, 또는 w-screen대형 요소 min-width.

In Safari Web Inspector, run:

[...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 태그 자체가 아닙니다.

결론

Capgo를 사용하여 기존 Nuxt 웹 애플리케이션을 native iOS 및 Android 앱으로 성공적으로 변환했습니다. Capacitor 8을 사용하여 Vue 코드베이스가 모바일 장치에서 실행되며 장치 API에 접근할 수 있습니다.

성공적으로 달성한 것:

  • Nuxt를 정적 생성으로 구성했습니다.
  • Capacitor 8을 추가하여 필수 플러그인을 설치했습니다.
  • iOS 및 Android 시뮬레이터로 빌드 및 배포했습니다.
  • 개발 중에 라이브 리로드를 활성화했습니다.
  • iOS 레이아웃 문제를 해결했습니다 (뷰포트, 안전 영역, 오버플로우)
  • Capgo 네이티브 네비게이션 및 전환을 사용하여 네이티브처럼 보이는 UI를 추가했습니다.

다음 단계:

  • 설정 Capgo 앱 스토어 재제출 없이 오버 더 에어 업데이트 가능
  • 카메라, 위치 정보, 푸시 알림 등 네이티브 플러그인 추가
  • 프로덕션용 앱 아이콘 및 스플래시 화면 구성
  • 애플 스토어 및 구글 플레이 제출을 위해 앱 준비

새로운 프로젝트 시작? Nuxt Mobile App을 처음부터 구축하는 방법 가이드된_walkthrough를 확인하세요.

자원

Capgo을 사용하여 더 나은 앱을 더 빠르게 빌드하는 방법을 알아보세요. __CAPGO_KEEP_0__에 대한 무료 계정으로 가입하세요 오늘.

Convert Your Nuxt App to iOS &amp; Android with Capacitor 8

Capgo를 사용 중이라면 Convert Your Nuxt App to iOS &amp; Android with Capacitor 8 자연스러운 플러그인 작업을 계획하고자 한다면 Capgo Plugin Directory와 연결하세요. Capgo Plugin Directory의 제품 워크플로우 Capacitor Plugins by Capgo Capacitor Plugins by Capgo의 구현 세부 사항 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항 Ionic Enterprise Plugin Alternatives Ionic Enterprise 플러그인 대체 제품의 제품 워크플로우에 대해 Capgo 네이티브 빌드 for the product workflow in Capgo Native Builds.

Capacitor 앱의 실시간 업데이트

Capgo을 사용하여 웹-layer 버그가 활성화된 경우 앱 스토어 승인 대기 없이 바로 픽스를 배포하세요. 사용자는 배경에서 업데이트를 받으며 네이티브 변경 사항은 일반적인 검토 경로에 남아 있습니다.

시작하기

블로그에서 최신 뉴스

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

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

Capacitor 앱에서 2중 통신

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

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

모바일 앱 실시간 업데이트에 대한 5 가지 보안 권장 사항
개발 모바일 +1
2025년 1월 14일

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

See all from our blog