소개
이미 Nuxt 웹 애플리케이션이 있는 경우, 이 가이드에서는 __CAPGO_KEEP_0__를 사용하여 iOS 및 Android 모바일 앱으로 변환하는 방법을 배울 것입니다. Capacitor 8 — 성능이 향상되고 새로운 기능이 추가된 최신 버전입니다.
Capacitor는 웹 앱을 네이티브 컨테이너에 감싸고, 기존의 Vue 코드베이스를 유지하면서 디바이스 API에 접근할 수 있도록 해줍니다. Flutter나 React Native와 달리, code를 다시 작성할 필요가 없습니다. Nuxt code는 그대로 작동합니다.
학습할 내용:
- 기존의 Nuxt 앱을 정적 생성을 위해 구성합니다.
- Capacitor 8에 필수적인 네이티브 플러그인을 추가합니다.
- iOS 및 Android 시뮬레이터에서 앱을 빌드하고 테스트합니다.
- 빠른 개발을 위해 라이브 리로드를 활성화합니다.
- iOS 레이아웃 문제를 해결합니다 (뷰포트, 안전 영역, 수평 방향 오버플로우).
- Capgo 네이티브 네비게이션 및 트랜지션을 사용하여 네이티브한 느낌의 UI를 추가합니다.
새 프로젝트를 시작하고 싶으신가요? 새로운 프로젝트를 시작하는 방법에 대한 가이드를 확인하세요. Nuxt 및 __CAPGO_KEEP_0__의 이점:.
Capacitor 재사용성:
- Code 재사용성__CAPGO_KEEP_0__ 재사용성:
- 성능: Nuxt의 정적 생성은 모바일용 최적화된 번들을 생성합니다.
- 자연스러운 기능: Capacitor 플러그인을 통해 카메라, 위치 정보, 파일 시스템과 같은 장치 기능에 접근할 수 있습니다.
- 간소화된 개발: 친숙한 Vue/Nuxt 패턴을 사용하여 네이티브 개발을 배워야 하는 것을 피할 수 있습니다.
준비 사항
: 시작하기 전에 다음을 확인하세요.
- Node.js 18+ 설치
- 기존 Nuxt 4 애플리케이션
- Xcode (iOS 개발을 위해 macOS만)
- 안드로이드 스튜디오 (Android 개발을 위해)
모바일을 위한 Nuxt 앱 설정
Nuxt 앱을 정적 생성하기 위해 첫 번째 단계는 정적 HTML/JS/CSS 파일을 생성하는 것입니다. Capacitor은 정적 HTML/JS/CSS 파일을 네이티브 앱으로 패키징하기 위해 필요합니다.
정적 HTML을 생성하기 위해 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"
}
}Important: 서버 사이드 기능을 사용 중이라면 (API 라우트, 서버 미들웨어 등) 클라이언트 사이드 대안 또는 외부 API를 사용해야 합니다.
__CAPGO_KEEP_0__
bun run generate이러한 앱을 만들기 위해 Native 모바일 앱을 빌드하는 방법에 대해 알아보겠습니다. .output/public static 파일 폴더입니다. 이 폴더의 파일은 Capacitor이 네이티브 앱에 패키징합니다.
Adding Capacitor 8 to Your Project
Nuxt 앱을 Native 모바일 컨테이너로 패키징하려면 다음 단계를 따르세요.
- Capacitor 코어 및 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/앱@Capgo/keyboard: 모바일 키보드 동작을 제어합니다.
- @capacitor/키보드@Capgo/notifications: 알림을 제어합니다.
- @capacitor/스플래시 화면: 모바일 앱의 네이티브 스플래시 화면 관리
- @capacitor/상태바: 디바이스 상태 바 스타일링
- @capacitor/설정: 키-값 스토리지 (localStorage와 유사하지만 네이티브)
- 프로젝트 세부 정보와 Capacitor 초기화:
bunx cap init my-app com.example.myapp --web-dir .output/publicReplace 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;- 네이티브 플랫폼 설치:
bun add @capacitor/ios @capacitor/android- 자연적인 모바일 앱을 만들기 위해 Native 플랫폼 폴더를 추가하세요:
bunx cap add ios
bunx cap add androidCapacitor은 Native 프로젝트 폴더를 생성합니다. ios 그리고 android 프로젝트의 루트 폴더에 Native 프로젝트 폴더가 생성됩니다.
Android 프로젝트를 빌드하려면 안드로이드 스튜디오가 필요합니다. iOS를 위해 Mac에 Xcode.
- 가 필요합니다. 프로젝트를 빌드하고 동기화하세요:
bun run mobile이것은 사용자 정의 스크립트를 실행하여 정적 Nuxt 빌드를 생성하고 Native 플랫폼과 파일을 동기화합니다.
자연적인 모바일 앱 빌드 및 배포
자연적인 모바일 앱을 빌드하고 배포하려면 다음 단계를 따르세요:
iOS 앱을 개발하려면 Xcode 이 설치되어야 합니다. Android 앱을 개발하려면 안드로이드 스튜디오 이 설치되어야 합니다. 또한 앱을 앱 스토어에 배포하려면 iOS에서는 Apple Developer Program에, Android에서는 Google Play Console에 가입해야 합니다.
- 자연스럽게 열어보세요:
iOS:
bun run mobile:iosAndroid:
bun run mobile:android직접으로는 Capacitor CLI으로도 가능합니다.
bunx cap open ios
bunx cap open android- __CAPGO_KEEP_0__
- 으로 열어보세요: 앱을 빌드하고 실행하세요: android-studio-run 안드로이드 스튜디오에서 프로젝트가 준비되기를 기다리세요. 그런 다음 연결된 장치나 에뮬레이터에 앱을 배포하기 위해 '실행' 버튼을 클릭하세요.
- In Xcode에서, 앱을 실제 기기에서 배포하기 위해 서명 계정을 설정하세요. 이 과정을 처음으로 진행하는 경우, Xcode는 Apple Developer Program에 가입되어 있어야 한다는 것을 알려줍니다. 설정이 완료되면, 연결된 기기에서 앱을 실행하기 위해 'Play' 버튼을 클릭하세요.
성공했습니다! Nuxt 웹 앱을 모바일 기기에서 성공적으로 배포했습니다.
하지만, 개발 중에는 더 빠른 방법이 있습니다...
Capacitor 실시간 리로드
개발 중에는 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;Replace YOUR_IP_ADDRESS 로컬 IP 주소 (예를 들어, 192.168.1.100).
- 자연스럽게 native 프로젝트에 변경 사항을 적용하세요:
bunx cap copyThe copy 명령어는 웹 폴더와 구성 변경 사항을 native 프로젝트로 복사하고 전체 프로젝트를 업데이트하지 않습니다.
- Nuxt 개발 서버를 시작하고 Xcode/Android Studio에서 다시 빌드하세요:
bun run dev이제 Nuxt 앱에 변경 사항을 만들면 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.
주의: 새로운 플러그인을 설치하거나 native 파일을 변경하면 live reloading이 웹 code 변경 사항만 적용되므로 native 프로젝트를 다시 빌드해야 합니다.
Capacitor 플러그인 사용
Capacitor 플러그인은 Nuxt 앱에서 native 장치 기능에 접근할 수 있도록 합니다. Capacitor 플러그인을 사용하는 방법에 대해 알아보겠습니다. 공유 플러그인 예를 들어:
- 공유 플러그인을 설치하세요:
bun add @capacitor/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>- 변경 사항을 네이티브 프로젝트와 동기화하세요:
bun run mobile만들기만 하면 됩니다:
bunx cap sync- 앱을 기기에서 실행하세요.
이제 '공유하기!' 버튼을 클릭하면 네이티브 공유 대화상자가 나타납니다.
다음으로, iOS와 Android에서 네이티브처럼 느껴지는 앱을 만들 수 있습니다. Capgo 네비게이션과 전환, iOS에서 발생하는 일반적인 레이아웃 문제를 해결할 수 있습니다. 예를 들어, 가로로 넘치거나 안전 영역이 잘려 나가는 문제를 해결할 수 있습니다.
네이티브처럼 느껴지는 UI와 Capgo 네이티브 네비게이션과 전환
수년 동안 아이오닉 다양한 플랫폼을 위한 애플리케이션을 만들기 위해, Nuxt와 통합하는 것은 불편하고 이미 가지고 있는 경우에 자주 사용되지 않습니다. Tailwind CSS.
Nuxt + Capacitor 앱에서 네이티브 모바일 느낌을 얻으려면, 웹 전용 UI 키트인 Konsta UI 대신 Capgo 플러그인을 사용하세요.
- @capgo/capacitor-자연스러운 네비게이션 — 네이티브 네비게이션 바, iOS에서 Liquid Glass 탭 바, Android에서 흐린 탭 바 스타일을 사용하세요. Nuxt 라우터는 라우트 상태를 유지하고 플러그인은 네이티브 창을 관리합니다.
- @capgo/capacitor-transition — Ionic-style 페이지 전환과 iOS 에지 스와이프-백을 WebView layer에서 사용하세요. Ionic 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>라우트된 페이지를 Wrap하세요: cap-router-outlet, cap-page, and cap-content, 그리고 호출 setDirection('forward') 또는 setDirection('back') 이전으로 이동하기 전에.
전체 가이드를 참조하십시오 Using @capgo/capacitor-native-navigation 그리고 @capgo/capacitor-전환 사용.
안전 영역에 대한 Tailwind
Tailwind CSS에서 디바이스 안전 영역을 사용하려면 @capgo/tailwind-capacitor (게시됨으로) tailwind-capacitor npm)에 대해 설명합니다. 그것은 safe-areas Capacitor-친화적인 Tailwind 플러그인을 포함하여
bun add -D tailwind-capacitorIn app/assets/css/main.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Nuxt 4와 Tailwind CSS 4를 사용하는 경우, CSS 파일에서 참조하는 nuxt.config.ts.
Tailwind CSS의 pt-safe, pb-safe을 사용하세요. px-safe 대신에 env(safe-area-inset-*) 을 수동으로 추가하지 마세요. 프로젝트는 활발히 개발 중이며, Nuxt 설정에 필요한 기능이 누락된 경우 GitHub에 대한 PR을 열어주세요..
iOS에서 콘텐츠가 잘려나거나-shifted되거나 가로 스크롤이 가능하다면,
또는 overflow-x: hidden 뷰포트 태그만 조정하는 것만으로는 해결되지 않습니다. 이 순서대로 체크하세요.
viewport meta 태그가 올바르게 적용되어야 합니다.
In nuxt.config.ts, __CAPGO_KEEP_0__을 통해 뷰포트를 설정하세요. app.head:
export default defineNuxtConfig({
app: {
head: {
meta: [
{
name: 'viewport',
content: 'width=device-width, initial-scale=1, viewport-fit=cover',
},
],
},
},
});iOS safe area를 한 루트 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안에 감싸세요. 여러 중첩된 컴포넌트에서 안전 영역 패딩을 두 번 적용하는 것은 UI가 잘린 것처럼 보이거나 너무 크게 보이는 것을 피하기 위해 자주 사용됩니다.
With @capgo/tailwind-capacitor와 함께, 동일한 패딩을 표현할 수 있는 유틸리티를 사용할 수 있습니다.__CAPGO_KEEP_0__을 사용하여 iOS pt-safe pb-safe px-safe __CAPGO_KEEP_0__을 사용하여 iOS
Capacitor을 사용하여 iOS contentInset to never first
In capacitor.config.ts, native inset을 사용하고 CSS (또는 Native Navigation의 )가 safe area를 관리하도록 하세요. contentInsetMode: 'css'Mixing __CAPGO_KEEP_0__의 자동 콘텐츠 inset과 CSS padding은 일반적인 double spacing의 원인입니다.
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
ios: {
contentInset: 'never',
},
};Mixing Capacitor의 자동 콘텐츠 인셋과 CSS를 혼합합니다. env(safe-area-inset-*) 일반적으로 부족한 요소는
, Tailwind
, 고정 픽셀 너비를 사용하는 요소, 또는 100vw, Tailwind w-screenfirst min-width.
In
[...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안전 영역의 중복 패딩 또는 고정 너비 컨테이너에서 오는 것이 아니라
Conclusion
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.
__CAPGO_KEEP_0__ 8을 사용하여 기존의 Nuxt 웹 애플리케이션을 iOS 및 Android 앱으로 성공적으로 변환했습니다.
- Vue 코드베이스는 이제 모바일 장치에서 실행되며 장치 API에 접근할 수 있습니다.
- Capacitor 8에 필수 플러그인을 추가했습니다.
- NUXT를 정적 생성으로 구성했습니다.
- __CAPGO_KEEP_0__ 8을 추가하여 필수 플러그인을 설치했습니다.
- iOS 및 Android 시뮬레이터에 빌드 및 배포했습니다.
- Capgo
다음 단계:
- 설정 Capgo 앱 스토어 재제출 없이 오버어어시 업데이트
- 카메라, 위치 정보, 푸시 알림 등 더 많은 네이티브 플러그인을 추가하세요
- 프로덕션용 앱 아이콘과 스플래시 화면을 구성하세요
- 앱 스토어와 구글 플레이 제출을 위해 앱을 준비하세요
새로운 프로젝트를 시작하고 싶으세요? 네이티브 모바일 앱을 처음부터 구축하는 방법 안내서를 따라서.
자원
- __CAPGO_KEEP_0__
- Capacitor 8 Capacitor
- capgo/capacitor-native-navigation --- Liquid Glass tab bar and native chrome
- capgo/capacitor-transitions --- native-feeling page transitions
- capgo/tailwind-capacitor --- Tailwind safe-area utilities for Capacitor
- Capgo - Capgo Live Updates for Capacitor Apps
Capgo의 Capgo을 사용하여 더 나은 앱을 더 빠르게 빌드하는 방법을 알아보세요. __CAPGO_KEEP_0__에 가입하세요. today.
iOS 및 Android 앱으로 전환하세요. Capacitor 8
__CAPGO_KEEP_0__을 사용 중이라면 Capacitor을 iOS 및 Android 앱으로 전환하세요. Capacitor 8 native 플러그인 작업을 계획하기 위해 연결하세요 Capgo Plugin Directory에서 제품 워크플로우를 확인하세요. Capgo Plugins by __CAPGO_KEEP_1__ Capacitor Plugins by Capgo에서 구현 세부 사항을 확인하세요. Capacitor 플러그인에 대한 구현 세부 사항은 Capgo에 의해 제공됩니다. 플러그인 추가 또는 업데이트에서 구현 세부 사항을 확인하세요. Ionic Enterprise Plugin Alternatives Ionic Enterprise Plugin 대체 옵션 Adding or Updating Plugins Capgo 네이티브 빌드 Capgo Native Builds
