Capacitor iOS & Android로 Nuxt 앱 변환

소개

이미 Nuxt 웹 애플리케이션이 있는 경우? Capacitor Capacitor

Capacitor wraps your web app in a native container, giving you access to device APIs like camera, filesystem, and push notifications while keeping your existing Vue codebase. Unlike Flutter or React Native, you don’t need to rewrite anything — your Nuxt code runs as-is.

Capacitor

Capacitor는 웹 애플리케이션을 네이티브 컨테이너에 감싸고, 기존 Vue 코드베이스를 유지하면서 기기 API에 접근할 수 있도록 해줍니다. Flutter나 React Native와 달리, 다시 작성할 필요가 없습니다. — Nuxt 애플리케이션은 그대로 작동합니다.
Add Capacitor 8 with essential native plugins
기존 Nuxt 앱을 정적 생성으로 구성합니다.
Capacitor 8에 필수 네이티브 플러그인을 추가합니다.
iOS 및 Android 시뮬레이터에서 빌드 및 테스트합니다.
Add native-feeling UI with Capgo Native Navigation and Transitions

새로운 프로젝트를 시작하려면? 넥스트 모바일 앱 만들기.

넥스트와 Capacitor 사용하는 이점

Code 재사용성: 웹과 모바일 앱 간에 Vue 컴포넌트와 로직을 공유할 수 있습니다.
성능역할: 섹션 또는 페이지 제목. 페이지: page premium-support.astro. 메시지 키 `ps_help_performance_title` (Ps Help Performance Title).
: 넥스트의 정적 생성은 모바일용 최적화된 번들을 생성합니다.: Access device features like camera, geolocation, and filesystem through Capacitor plugins.
: 카메라, 위치 정보, 파일 시스템과 같은 장치 기능에 접근할 수 있습니다.간소화된 개발

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

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

Node.js 18 이상이 설치되어야 합니다. 설치되어야 합니다.
이미 존재하는 Nuxt 4 애플리케이션
Xcode (iOS 개발을 위해 macOS만)
Android Studio (Android 개발을 위해)

모바일을 위한 Nuxt 앱 설정

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

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를 사용해야 합니다.

정적 생성을 테스트하려면 다음 명령어를 실행하세요:

bun run generate

정적 생성이 성공적으로 완료되면 .output/public 폴더에 정적 파일이 생성됩니다. 이 파일들은 Capacitor가 네이티브 앱에 패키징할 파일입니다.

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

네이티브 모바일 컨테이너로 패키징할 수 있도록 Nuxt 앱을 구성하려면 다음 단계를 따르세요:

Capacitor core 및 CLI을 설치하세요:

bun add @capacitor/core
bun add -D @capacitor/cli

필요한 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와 유사한 네이티브 저장소)

Initialize Capacitor with your project details:

bunx cap init my-app com.example.myapp --web-dir .output/public

바꾸기 my-app 앱 이름과 함께 com.example.myapp 역 도메인 표기법을 사용하는 앱 ID와 함께

적절한 구성으로 capacitor.config.ts 파일을 생성하거나 업데이트:

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;

자연/native 플랫폼을 설치:

bun add @capacitor/ios @capacitor/android

자연/native 플랫폼 폴더를 추가:

bunx cap add ios
bunx cap add android

Capacitor은 ios 프로젝트의 루트 폴더에 자연/native 프로젝트를 포함하는 폴더를 생성합니다. android Android 프로젝트를 빌드하려면

Android Studio가 필요합니다. iOS를 위해 Mac이 필요합니다.. For iOS, you need a Mac with Xcode.

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

bun run mobile

이것은 사용자 정의 스크립트를 실행하여 정적 Nuxt 빌드를 생성하고 네이티브 플랫폼과 파일을 동기화합니다.

네이티브 앱 빌드 및 배포

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

iOS 앱을 개발하려면 Xcode가 설치되어야 하며, Android 앱을 개발하려면 Android Studio가 설치되어야 합니다. 또한 앱 스토어에 앱을 배포하려면 iOS에서는 Apple Developer Program에 등록하고, Android에서는 Google Play Console에 등록해야 합니다. 네이티브 프로젝트를 열세요: iOS 경우: __CAPGO_KEEP_0__ __CAPGO_KEEP_1__

__CAPGO_KEEP_2__

__CAPGO_KEEP_3__

bun run mobile:ios

안드로이드에 대해:

bun run mobile:android

Capacitor CLI

bunx cap open ios
bunx cap open android

앱을 빌드하고 실행하세요:

android-studio-run

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

xcode-run

Xcode에서 앱을 실제 장치에 배포하기 위해 서명 계정을 설정하십시오. 이 과정을 처음으로 진행하시는 경우 Xcode는 앱을 개발자 프로그램에 등록된 상태로 되어 있어야 한다는 안내를 제공하실 것입니다. 설정이 완료되면 "실행" 버튼을 클릭하여 연결된 장치에서 앱을 실행하십시오.

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

하지만, 개발 중에는 더 빠른 방법이 있습니다...

Capacitor Live Reload

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

내 로컬 IP 주소를 찾으세요:

macOS에서 터미널에서 다음 명령어를 실행하세요:
```
ipconfig getifaddr en0
```
Windows에서 실행하세요:
```
ipconfig
```
출력에서 IPv4 주소를 찾으세요.

개발 서버로 가기 위해 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 에 192.168.1.100).

예를 들어

bunx cap copy

변경 사항을 네이티브 프로젝트에 적용하세요: copy 명령어는 웹 폴더와 구성 변경 사항을 네이티브 프로젝트로 복사하지만 전체 프로젝트를 업데이트하지 않습니다.

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

bun run dev

이제 Nuxt 앱에 대한 변경 사항이 있으면 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.

참고: 새로운 플러그인을 설치하거나 네이티브 파일에 변경 사항이 있으면 네이티브 프로젝트를 다시 빌드해야 합니다. 왜냐하면 라이브 리로딩은 웹 code 변경 사항만 적용되기 때문입니다.

Capacitor 플러그인 사용

Capacitor 플러그인은 Nuxt 앱에서 네이티브 디바이스 기능에 접근할 수 있도록 해줍니다. Share 플러그인을 예로 들어보겠습니다. Share 플러그인 설치 Share 플러그인을 사용하는 페이지를 만들거나 업데이트 해보세요. Nuxt 4에서는 페이지가

변경 사항을 네이티브 프로젝트와 동기화하세요:

bun add @capacitor/share

또는 다시 빌드하지 않고 동기화만 해보세요: 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>

앱을 다시 빌드하고 디바이스에서 실행하세요.

bun run mobile

__CAPGO_KEEP_0__

bunx cap sync

__CAPGO_KEEP_0__

Now, when you click the “Share now!” button, the native share dialog will appear.

다음으로, 앱을 iOS 및 Android에서 더 원시적인 느낌으로 만들 수 있습니다. Capgo 네비게이션 및 전환을 사용하여 일반적인 iOS 레이아웃 문제를 해결하고 수평 스크롤 또는 안전 영역이 잘려 나가는 문제를 해결할 수 있습니다.

저는 여러 해 동안 Ionic을 사용하여 크로스 플랫폼 애플리케이션을 개발했습니다. 그러나 Nuxt와 통합하는 것은 hacky하고, 이미 Tailwind CSS를 사용하고 있다면 rarely worth입니다. Native-feeling UI를 위해 Nuxt + __CAPGO_KEEP_0__ 앱에서 __CAPGO_KEEP_1__ 플러그인을 사용하는 것이 더 좋습니다. 웹 전용 UI 키트인 Konsta UI와 같은 UI 키트를 사용하는 대신: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation — 네이티브 네비게이션, iOS에서 Liquid Glass 탭 바, Android에서 흐린 탭 바 스타일. Nuxt 라우터는 라우트 상태를 유지하고 플러그인은 네이티브 창을 관리합니다. @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions — WebView layer에서 Ionic-style 페이지 전환 및 iOS 에지 스와이프 백, Ionic UI를 채택하지 않고도..

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 Ionic
@capgo/capacitor-transitions Konsta 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',
  },
});

리퀴드 글라스 탭 바를 렌더링하세요 (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') 자연스러운 네비게이션을 위해 CSS inset 모드를 구성하여 웹 콘텐츠가 네이티브 바를 존중하도록 하세요. 네이티브 네비게이션은 웹 헤더 또는 푸터를 중복하지 마세요.

전체 가이드를 참조하세요: Using @capgo/capacitor-native-navigation 및 Capacitor @capgo/capacitor-transitions.

안전 영역에 대한 Tailwind

Tailwind CSS에서 장치 안전 영역을 사용하려면 Capacitor @capgo/tailwind-capacitor (__CAPGO_KEEP_0__에서 출판) tailwind-capacitor npm에서 safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

Tailwind CSS의 유용한 __CAPGO_KEEP_0__-친화적인 플러그인: app/assets/css/main.css:

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

In nuxt.config.ts.

Nuxt 4와 Tailwind CSS 4를 사용할 때, CSS 파일에서 다음 import를 유지하세요. pt-safe, pb-safeTailwind CSS의 유용한 __CAPGO_KEEP_0__-친화적인 플러그인: px-safe In env(safe-area-inset-*) 손으로. Nuxt 설정에 필요한 모든 것이 없다면 __CAPGO_KEEP_0__ GitHub 에서 PR을 열어주세요.

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

iOS에서 콘텐츠가 잘려나거나-shifted 또는 가로 스크롤이 가능하다면, 더 많은 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, utility와 같은 패딩을 표현할 수 있습니다. pt-safe pb-safe px-safe 단일 shell에서

Capacitor iOS `contentInset` 를 `never` 첫 번째로

In capacitor.config.ts, contentInsetMode: 'css'CSS (또는 Native Navigation의)

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-*) CSS 패딩과 __CAPGO_KEEP_0__의 자동 콘텐츠 인셋을 혼합하는 것은 두 번의 간격이 발생하는 일반적인 원인입니다.

실제로 넘치고 있는 요소 찾기

일반적으로 범인은 픽셀 너비가 고정된 요소 또는 큰 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 태그 자체에서 오는 것이 아니다.

결론

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

성공적으로 달성한 것:

Nuxt를 정적 생성에 구성했습니다.
Capacitor 8에 필수 플러그인을 추가했습니다.
iOS 및 Android 시뮬레이터로 빌드 및 배포했습니다.
개발 중에 라이브 리로드를 활성화했습니다.
일반 iOS 레이아웃 문제를 해결했습니다 (뷰포트, 안전 영역, 오버플로우).
Capgo Native Navigation 및 Transitions를 사용하여 네이티브 느낌의 UI를 추가했습니다.

다음 단계:

설정 Capgo 앱 스토어 재제출 없이 오버 더 에어 업데이트
카메라, 위치 정보, 푸시 알림과 같은 더 많은 네이티브 플러그인을 추가하세요.
배포용 앱 아이콘 및 스플래시 화면을 구성하세요.
애플리케이션을 App Store와 Google Play 제출 준비하기

새로운 프로젝트를 시작하고 싶으신가요? Nuxt 모바일 앱을 처음부터 만들기 가이드된_walkthrough를 확인하세요.

자원

Nuxt 문서
Capacitor 8 문서
@capgo/capacitor-native-navigation — Liquid Glass 탭바와 네이티브 크롬
@capgo/capacitor-transitions — 네이티브 느낌의 페이지 전환
@capgo/tailwind-capacitor — Tailwind safe-area utilities for Capacitor
Capgo - Live Updates for Capacitor Apps

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

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

__CAPGO_KEEP_0__을 사용 중이라면 Capacitor 8을 사용하여 iOS & Android 앱으로 변환하세요. 자연 플러그인 작업을 계획하려면 __CAPGO_KEEP_0__ Plugin Directory와 연결하세요. Capgo Plugin Directory에서 제품 워크플로우와 Capgo Plugin Directory를 연결하세요. Capgo Plugins by __CAPGO_KEEP_1__ Capacitor Plugins by Capgo Capacitor 플러그인에 대한 구현 세부 정보는 Capgo 플러그인에 의해 제공됩니다. 플러그인 추가 또는 업데이트 __CAPGO_KEEP_0__ 플러그인에 대한 구현 세부 정보는 플러그인 추가 또는 업데이트에 의해 제공됩니다. 아이오닉 엔터프라이즈 플러그인 대체 아이오닉 엔터프라이즈 플러그인 대체에 대한 제품 워크플로우, 그리고 Capgo 네이티브 빌드 Capgo 네이티브 빌드에 대한 제품 워크플로우.

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

소개

넥스트와 Capacitor 사용하는 이점

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

모바일을 위한 Nuxt 앱 설정

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

네이티브 앱 빌드 및 배포

Capacitor Live Reload

Capacitor 플러그인 사용

원시적인 UI를 위해 Capgo 네이티브 네비게이션 및 전환을 사용합니다.

안전 영역에 대한 Tailwind

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

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

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

Capacitor iOS `contentInset` 를 `never` 첫 번째로

실제로 넘치고 있는 요소 찾기

결론

자원

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

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

소개

넥스트와 Capacitor 사용하는 이점

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

모바일을 위한 Nuxt 앱 설정

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

네이티브 앱 빌드 및 배포

Capacitor Live Reload

Capacitor 플러그인 사용

원시적인 UI를 위해 Capgo 네이티브 네비게이션 및 전환을 사용합니다.

안전 영역에 대한 Tailwind

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

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

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

Capacitor iOS contentInset 를 never 첫 번째로

실제로 넘치고 있는 요소 찾기

결론

자원

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

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

Capacitor iOS `contentInset` 를 `never` 첫 번째로

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