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

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

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

마틴 도나디우

마틴 도나디우

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

소개

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

Capacitor은 웹 앱을 네이티브 컨테이너에 감싸고, 카메라, 파일 시스템, 푸시 알림과 같은 장치 API에 접근할 수 있도록 해줍니다. existing Vue 코드베이스를 유지하면서, Flutter 또는 React Native와 달리 다시 작성할 필요가 없습니다. — Nuxt code은 그대로 실행됩니다.

학습할 내용:

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

새로운 프로젝트를 시작하고 싶으신가요? 시작부터 끝까지의 가이드인 Nuxt 모바일 앱을 만드는 방법.

Nuxt 및 Capacitor 사용의 이점

  • Code 재사용성: 모바일 앱과 웹 앱 간에 Vue 컴포넌트 및 로직을 공유하세요.
  • 성능페이지/영역: 홈페이지 문제/해결 섹션. 역할: 섹션 또는 페이지 제목. 표시되는 곳: page premium-support.astro. 메시지 키 `ps_help_performance_title` (Ps Help Performance Title).
  • : Nuxt의 정적 생성이 모바일용 최적화된 번들을 생성합니다.: Access device features like camera, geolocation, and filesystem through Capacitor plugins.
  • : __CAPGO_KEEP_0__ 플러그인을 통해 카메라, 위치 정보, 파일 시스템과 같은 장치 기능에 접근하세요.간소화된 개발

: 익숙한 Vue/Nuxt 패턴을 사용하여 네이티브 개발을 배워야 할 필요가 없습니다.

준비 사항

  • 시작하기 전에 다음을 확인하세요: Node.js 18+
  • 설치되었습니다 Nuxt 4 애플리케이션
  • Xcode (iOS 개발을 위해 macOS만)
  • Android Studio (Android 개발을 위해)

Nuxt 앱을 모바일로 설정하는 방법

첫 번째 단계는 Nuxt 앱을 정적 생성으로 설정하는 것입니다. Capacitor은 정적 HTML/JS/CSS 파일을 모바일 앱으로 패키징하기 위해 필요합니다.

generate 스크립트가 있는지 확인하세요. 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"
  }
}

서버 사이드 기능을 사용하고 있다면 (__CAPGO_KEEP_0__ 라우트, 서버 미들웨어 등), 클라이언트 사이드 대체 또는 외부 API를 사용해야 합니다. API

테스트를 위해 다음 명령어를 실행하세요:

bun run generate

정적 생성을 테스트할 때 .output/public 정적 파일이 포함된 폴더를 볼 수 있습니다. 이 폴더는 Capacitor가 네이티브 앱에 패키징할 것입니다.

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

네이티브 모바일 컨테이너에 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

__CAPGO_KEEP_0__/app: 앱의 라이프사이클 이벤트를 처리합니다 (전면/후면, 깊이 링크)

  • capacitor/keyboard: 모바일 키보드의 동작을 제어합니다__CAPGO_KEEP_0__
  • @capacitor/keyboard__CAPGO_KEEP_0__
  • @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 with your app ID (reverse domain notation).

  1. 앱 ID (역 도메인 표기법)으로 대체 capacitor.config.ts Create or update the file with the proper configuration:
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. Native 플랫폼 설치:
bun add @capacitor/ios @capacitor/android
  1. native 플랫폼 폴더 추가:
bunx cap add ios
bunx cap add android

Capacitor은 ios 그리고 android 프로젝트의 루트 폴더에 native 프로젝트를 포함하는 폴더가 생성됩니다.

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

  1. 가 필요합니다. Mac
bun run mobile

프로젝트를 빌드하고 동기화하세요:

이것은 Nuxt 정적 빌드와 native 플랫폼을 동기화하는 커스텀 스크립트를 실행합니다.

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

Or directly with Capacitor CLI:

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

android-studio-run

  • In Android Studio, __CAPGO_KEEP_0__ 프로젝트가 준비되기를 기다리십시오. 그런 다음 연결된 장치 또는 에뮬레이터에 앱을 배포하기 위해 “실행” 버튼을 클릭하십시오.

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. 자연스럽게 native 프로젝트에 변경 사항을 적용하세요:
bunx cap copy

는 copy 명령어는 웹 폴더와 구성 변경 사항을 native 프로젝트로 복사하고 전체 프로젝트를 업데이트하지 않습니다.

  1. Xcode/Android Studio에서 Nuxt 개발 서버를 시작하고 다시 빌드하세요:
bun run dev

이제 Nuxt 앱에 변경 사항을 추가할 때마다 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.

주의: 새로운 플러그인을 설치하거나 native 파일을 변경하면 live reloading이 웹 code 변경 사항만 적용되므로 native 프로젝트를 다시 빌드해야 합니다.

Capacitor 플러그인을 사용하세요

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

  1. Share 플러그인을 설치하세요:
bun add @capacitor/share
  1. Share 플러그인을 사용하는 페이지를 생성하거나 업데이트하세요. 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에서 네이티브처럼 보이게 하기 위해 Capgo 네비게이션과 전환, 그리고 iOS에서 발생하는 수평 스크롤이나 안전 영역이 잘려나가는 문제를 해결하세요.

네이티브처럼 보이는 UI와 Capgo 네이티브 네비게이션과 전환

나는 여러 해 동안 아이오닉 cross-platform 애플리케이션을 만들기 위해 사용하지만, Nuxt와 통합하는 것은 불편하고 이미 가지고 있는 경우에 자주 사용하지 않습니다. Tailwind CSS.

For a native mobile feel in a Nuxt + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

  • @capgo/capacitor-native-navigation — 네이티브 네비게이션 바, iOS에서 Liquid Glass 탭 바, Android에서 흐린 탭 바 스타일을 사용합니다. Nuxt 라우터는 라우트 상태를 유지하고 플러그인은 네이티브 크롬을 관리합니다.
  • @capgo/capacitor-transitions — 아이오닉 스타일의 페이지 전환과 iOS의 에지 스와이프 백을 WebView layer에서 사용할 수 있습니다. 아이오닉 UI를 채택하지 않습니다.

두 가지 모두 설치하세요.

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>

페이지를 감싸고 cap-router-outlet, cap-page, 그리고 cap-content, 그리고 호출 setDirection('forward') 또는 setDirection('back') 이동하기 전에. 네이티브 네비게이션에서 웹 헤더 또는 푸터를 중복하지 마십시오.

자세한 안내서를 참조하십시오: Using @capgo/capacitor-native-navigation 및 Using @capgo/capacitor-transitions.

안전 영역에 Tailwind

Tailwind CSS에서 장치 안전 영역을 사용하려면 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__으로 출판) tailwind-capacitor on npm. safe-areas Capacitor에서 제공하는

bun add -D tailwind-capacitor

Nuxt 4와 Tailwind CSS 4를 사용하는 경우, CSS 파일에서 다음 import를 유지하세요. 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 4를 사용하는 경우, CSS 파일에서 다음 import를 유지하세요. pt-safe, pb-safeTailwind CSS 4를 사용하는 경우, CSS 파일에서 다음 import를 유지하세요. px-safe Nuxt 4와 Tailwind CSS 4를 사용하는 경우, CSS 파일에서 다음 import를 유지하세요. env(safe-area-inset-*) Nuxt 4와 Tailwind CSS 4를 사용하는 경우, CSS 파일에서 다음 import를 유지하세요. open a PR on GitHub.

Nuxt 4와 Tailwind CSS 4를 사용하는 경우, CSS 파일에서 다음 import를 유지하세요.

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

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

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가 잘린 것처럼 보이거나 너무 큰 것처럼 보이는 경우가 있습니다.

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

Set Capacitor iOS contentInset 로 never 처음

In capacitor.config.ts, native inset을 비활성화하고 CSS (또는 Native Navigation의) contentInsetMode: 'css'Mixing __CAPGO_KEEP_0__’s 자동 콘텐츠 인셋과 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-*) 실제로 부풀어 오르는 요소를 찾으세요

일반적으로 원인은

, 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 태그 자체에서 오지 않습니다.

결론

You’ve successfully converted your existing Nuxt web application into native iOS and Android apps using Capacitor 8. Your Vue codebase now runs natively on mobile devices with access to device APIs.

성공적으로 달성한 것:

  • Nuxt를 정적 생성으로 구성했습니다.
  • Added Capacitor 8 with essential plugins
  • iOS 및 Android 시뮬레이터로 빌드 및 배포했습니다.
  • 개발 중에 라이브 리로드를 활성화했습니다.
  • iOS 레이아웃 문제를 해결했습니다 (뷰포트, 안전 영역, 오버플로우)
  • Capgo Native Navigation 및 전환을 사용하여 원활한 네이티브 UI를 추가했습니다

다음 단계:

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

새로운 프로젝트를 시작하고 싶으세요? 네이티브 모바일 앱을 만드는 방법을 알아보세요 부터 시작하세요

자원

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

Capacitor으로 Nuxt 앱을 iOS &amp; Android로 변환하세요. Capacitor 8

이미 __CAPGO_KEEP_0__을 사용하고 계신가요? Capacitor으로 Nuxt 앱을 iOS &amp; Android로 변환하세요. Capacitor 8 __CAPGO_KEEP_0__을 사용하여 __CAPGO_KEEP_0__ Plugin Directory와 연결하세요. Capgo Plugin Directory Capgo Plugin Directory에서 Capgo Plugins by __CAPGO_KEEP_1__ Capacitor Plugins by Capgo Capacitor Plugins by Capgo에서 구현 세부 정보 __CAPGO_KEEP_0__ Plugins by __CAPGO_KEEP_1__에서 구현 세부 정보 플러그인을 추가하거나 업데이트 플러그인을 추가하거나 업데이트에서 구현 세부 정보 Capgo 제품 워크플로우에 대하여 Ionic Enterprise Plugin Alternatives, 그리고 Capgo Native Builds Capgo 제품 워크플로우에 대하여 Capgo Native Builds.

Capacitor 앱에 대한 실시간 업데이트

When a web-layer bug is live, ship the fix through Capgo instead of waiting days for app store approval. Users get the update in the background while native changes stay in the normal review path.

웹层 버그가 활성화되면 __CAPGO_KEEP_0__을 통해修정을 배포하는 대신 앱 스토어 승인까지 며칠 기다리지 말고. 사용자는 배경에서 업데이트를 받으면 native 변경 사항은 normal 리뷰 경로에 남아있다.

컨텍스트: Capgo 마케팅 웹사이트. 역할: 지원 설명 문장 또는 메타 설명. 보존: Capgo 제품/브랜드 및 개발자 용어 정확히. 메시지 키 `instant_updates_for_capacitor_apps_description` (Capacitor 앱에 대한 즉시 업데이트 설명)

마틴의 인간 지원

Capgo gives you the best insights you need to create a truly professional mobile app.

2-Way Communication in Capacitor Apps
최신 뉴스 컨텍스트: Capgo 마케팅 웹사이트. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 보존: page blog/[slug].astro. 메시지 키 `latest_from_news` (최신 뉴스) +1
2025년 4월 26일

Capacitor 앱에서 2방향 통신

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

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

모바일 앱 라이브 업데이트의 5가지 보안 권장 사항
개발 모바일 +1
2025년 1월 14일

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

모든 블로그 글 보기