소개
__CAPGO_KEEP_0__ Capacitor 8 — 성능이 향상되고 새로운 기능이 추가된 최신 버전 __CAPGO_KEEP_0__ 8 — 성능이 향상되고 새로운 기능이 추가된 최신 버전
Capacitor은 웹 앱을 네이티브 컨테이너에 감싸줍니다. 이로써 카메라, 파일 시스템, 푸시 알림과 같은 장치 API에 접근할 수 있으면서도 기존의 React 코드베이스를 유지할 수 있습니다. React Native와 달리, code을 사용하는 Next.js 앱은 기존의 코드를 다시 작성하지 않아도 됩니다.
학습할 내용:
- 기존의 Next.js 앱을 정적 내보내기 위해 구성합니다.
- Capacitor 8에 필수적인 네이티브 플러그인을 추가합니다.
- iOS와 Android 시뮬레이터에서 빌드하고 테스트합니다.
- 빠른 개발을 위해 라이브 리로드를 활성화합니다.
- iOS에서 일반적인 레이아웃 문제를 해결합니다 (뷰포트, 안전 영역, 수평적 오버플로우).
- Capgo Native Navigation과 Transitions를 사용하여 네이티브한 느낌의 UI를 추가합니다.
새로운 프로젝트를 시작하려면? 기존의 Next.js 앱을 사용하여 모바일 앱을 빌드하는 방법에 대한 가이드를 확인하세요..
Capacitor의 이점:
- Code 재사용성: Next.js는 웹 앱과 모바일 앱 간에 재사용 가능한 컴포넌트를 작성하고 code를 공유할 수 있으므로 개발 시간과 노력을 절약할 수 있습니다.
- 성능Next.js는 서버 사이드 렌더링 및 code 분할과 같은 내장 성능 최적화 기능을 제공하여 빠른 로딩 시간과MOOTH한 사용자 경험을 보장합니다.
- 자연스러운 기능: 모바일 앱을 빌드할 때 Capacitor는 카메라, 위치 정보 및 기타 기능에 대한 접근 권한을 제공하여 기능-rich한 모바일 앱을 빌드할 수 있습니다.
- 간소화된 개발: Capacitor를 사용하면 모바일 앱을 개발하고 테스트할 때 익숙한 웹 기술을 사용할 수 있으므로 학습 곡선이 줄어들고 개발 프로세스가 단순화됩니다.
준비 사항
시작하기 전에 다음을 확인하세요:
- Node.js 18+ 설치
- 이미 존재하는 Next.js 15+ 애플리케이션
- Xcode (iOS 개발을 위해 macOS 전용)
- Android Studio (Android 개발을 위해)
Next.js 앱을 모바일로 구성하는 방법
첫 번째 단계는 Next.js 앱을 정적 내보내기로 구성하는 것입니다. Capacitor는 정적 HTML/JS/CSS 파일을 네이티브 앱으로 패키징하기 위해 필요합니다.
파일을 열어 next.config.js (또는 next.config.ts) 파일을 열어
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;
export output: 'export' __CAPGO_KEEP_0__ images: { unoptimized: true } Next.js를 사용하여 정적 HTML 파일을 생성하도록 설정하고
Next.js의 이미지 최적화를 생략합니다. 이는 서버가 필요합니다. If you’re using features that require a server (API routes, server components with data fetching, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.
서버가 필요한 기능을 사용 중이라면 (__CAPGO_KEEP_0__ 라우트, 데이터를 가져오는 서버 컴포넌트 등), 클라이언트 측 대안 또는 외부 API를 사용하도록 리팩토링해야 합니다. package.json:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint",
"mobile": "bun run build && bunx cap sync",
"mobile:ios": "bun run mobile && bunx cap open ios",
"mobile:android": "bun run mobile && bunx cap open android"
}
}
모바일 전용 스크립트를 프로젝트에 추가하세요.
bun run build
정적 내보내기 테스트를 위해 다음 명령어를 실행하세요: out folder at the root of your project. This contains all the static files that Capacitor will bundle into your native app.
프로젝트의 루트 폴더에 폴더가 생성됩니다. 이 폴더에는 Capacitor가 모바일 앱에 포함할 정적 파일이 포함되어 있습니다.
__CAPGO_KEEP_0__ 8을 프로젝트에 추가하는 방법
- Install Capacitor core and CLI:
bun add @capacitor/core
bun add -D @capacitor/cli
- Capacitor core 및 __CAPGO_KEEP_1__을 설치하세요.
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferences
이 플러그인은 다음 기능을 제공합니다:
- @capacitor/app: 앱의 라이프 사이클 이벤트 (전경/후경, URL)를 처리합니다.
- @capacitor/keyboard: 모바일 키보드 동작을 제어합니다.
- @capacitor/splash-screen: 네이티브 스플래시 스크린을 관리합니다.
- @capacitor/preferences: 키-값 데이터를 영구적으로 저장합니다.
- Initialize Capacitor with your project details:
bunx cap init my-app com.example.myapp --web-dir out
Replace my-app 앱 이름과 com.example.myapp __CAPGO_KEEP_0__
- 앱 ID (역 도메인 표기법)
capacitor.config.ts생성 또는 업데이트
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
plugins: {
SplashScreen: {
launchShowDuration: 2000,
launchAutoHide: true,
androidScaleType: 'CENTER_CROP',
showSpinner: false,
splashFullScreen: true,
splashImmersive: true,
},
},
};
export default config;
- 파일에 올바른 구성:
bun add @capacitor/ios @capacitor/android
- 자연어 플랫폼 설치:
bunx cap add ios
bunx cap add android
Capacitor ios 와 android 프로젝트의 루트 폴더에 있는 네이티브 프로젝트 폴더
Android 프로젝트를 빌드하려면 Android Studio. iOS 프로젝트를 빌드하려면 Mac에서 Xcode.
- 프로젝트를 빌드하고 동기화하세요:
bun run mobile
이것은 Next.js 프로젝트를 빌드하고 정적 파일을 네이티브 플랫폼과 동기화하는 커스텀 스크립트를 실행합니다.
네이티브 앱 빌드 및 배포
네이티브 모바일 앱을 빌드하고 배포하려면 다음 단계를 따르세요: iOS 앱을 개발하려면 Xcode가 설치되어야 하며, Android 앱을 개발하려면 Android Studio가 설치되어야 합니다. 또한 앱 스토어에서 앱을 배포하려면 iOS에서는 Apple Developer Program에 가입하고, Android에서는 Google Play Console에 가입해야 합니다. 네이티브 프로젝트를 열세요: iOS: Android: 또는 직접 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__:
- Building and Deploying Native Apps
To build and deploy your native mobile app, follow these steps: To develop iOS apps, you need to have Xcode installed, and for Android apps, you need to have Android Studio installed. Moreover, if you plan to distribute your app on the app store, you need to enroll in the Apple Developer Program for iOS and the Google Play Console for Android.
bun run mobile:ios
Open the native projects:
bun run mobile:android
For iOS: For Android: Or directly with Capacitor CLI:
bunx cap open ios
bunx cap open android
- 모바일 앱을 빌드하고 실행하세요:

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

-
Xcode에서 실제 장치에 앱을 배포하기 위해 서명 계정을 설정하십시오. 이 과정을 처음으로 진행하시는 경우 Xcode는 Apple Developer Program에 가입한 경우에만 이 과정을 안내하십니다. 설정이 완료되면 "재생" 버튼을 클릭하여 연결된 장치에서 앱을 실행하십시오.
축하합니다! Next.js 웹 앱을 성공적으로 모바일 장치에 배포했습니다.
Capacitor Live Reload
개발 중에는 즉시 변경 사항을 모바일 장치에서 확인할 수 있는 Live Reload 기능을 사용할 수 있습니다. 이 기능을 활성화하려면 다음 단계를 따르십시오:
- 내부 IP 주소를 찾으십시오:
-
macOS에서 터미널에서 다음 명령어를 실행하십시오:
ipconfig getifaddr en0 -
On Windows, run:
ipconfigIPv4 주소는 출력에서 찾으세요.
- Update your
capacitor.config.ts로 개발 서버에 포인트하세요:
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'out',
server: {
url: 'http://YOUR_IP_ADDRESS:3000',
cleartext: true,
},
};
export default config;
Replace YOUR_IP_ADDRESS 로 로컬 IP 주소 (예를 들어, 192.168.1.100).
- native 프로젝트에 변경 사항을 적용하세요:
bunx cap copy
The copy 명령어는 웹 폴더와 구성 변경 사항을 native 프로젝트로 복사하고 전체 프로젝트를 업데이트하지 않습니다.
- Android Studio 또는 Xcode를 사용하여 기기에서 앱을 다시 빌드하고 실행하세요.
이제, Next.js 앱에 변경 사항을 만들면 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.
주의: 새로운 플러그인을 설치하거나 native 파일에 변경 사항을 만들면 live reloading이 웹 code 변경 사항만 적용되므로 native 프로젝트를 다시 빌드해야 합니다.
Capacitor 플러그인 사용
Capacitor 플러그인은 Next.js 앱에서 네이티브 디바이스 기능에 접근할 수 있도록 해줍니다. 예를 들어 Share 플러그인을 사용해 보겠습니다. Share 플러그인 Share 플러그인을 설치하려면:
- __CAPGO_KEEP_0__ 파일을 업데이트하여 Share 플러그인을 사용하도록 하세요.
bun add @capacitor/share
- 변경 사항을 네이티브 프로젝트와 동기화하세요.
pages/index.js이전 섹션에서 언급했듯이 새로운 플러그인을 설치할 때는 동기화 작업을 수행하고 앱을 다시 배포해야 합니다. 이를 위해 다음 명령어를 실행하세요.
import Head from 'next/head';
import styles from '../styles/Home.module.css';
import { Share } from '@capacitor/share';
export default function Home() {
const share = async () => {
await Share.share({
title: 'Open Youtube',
text: 'Check new video on youtube',
url: 'https://www.youtube.com',
dialogTitle: 'Share with friends',
});
};
return (
<div className={styles.container}>
<Head>
<title>Create Next App</title>
<meta name="description" content="Generated by create next app" />
<link rel="icon" href="/favicon.ico" />
</Head>
<main className={styles.main}>
<h1 className={styles.title}>
Welcome to <a href="https://nextjs.org">Capgo!</a>
</h1>
<p className={styles.description}>
<h2>Cool channel</h2>
<button onClick={() => share()}>Share now!</button>
</p>
</main>
</div>
);
}
- 또는 재빌드 없이 동기화만 수행하세요.
앱을 디바이스에 다시 빌드하고 실행하세요.
bun run mobile
이제 '공유하기!' 버튼을 클릭하면 네이티브 공유 대화상자가 나타나, 콘텐츠를 다른 앱과 공유할 수 있습니다.
bunx cap sync
- 이전 섹션에서 언급했듯이 새로운 플러그인을 설치할 때는 동기화 작업을 수행하고 앱을 다시 배포해야 합니다.
이전 섹션에서 언급했듯이 새로운 플러그인을 설치할 때는 동기화 작업을 수행하고 앱을 다시 배포해야 합니다.
여러 해 동안 Ionic을 사용하여 크로스 플랫폼 앱을 개발해 왔습니다. Ionic Tailwind CSS 4와 함께 이미 사용 중인 __CAPGO_KEEP_0__와 Next.js를 통합하는 것은 복잡하고 거의 가치가 없습니다. Next.js + __CAPGO_KEEP_0__ 앱에서 원시적인 모바일 경험을 원한다면, 웹 전용 UI 키트인 Konsta UI 대신 __CAPGO_KEEP_1__ 플러그인을 사용하세요:.
@Capacitor/Capgo-native-navigation
- @capgo/capacitor-native-navigation @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions
- @capgo/capacitor-transitions 두 가지 모두 설치하세요:
__CAPGO_KEEP_0__
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync
자연/native 네비게이션을 구성하기 위해 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}`);
});
애플리케이션 셸에서 네이티브 페이지 전환을 추가하세요:
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });
페이지 라우팅을 위한 컴포넌트를 Wrap routed pages in __CAPGO_KEEP_0__ Native Mobile App에서 사용할 수 있도록 하려면, Native Mobile App에서 사용할 수 있는 __CAPGO_KEEP_0__ Capacitor API를 사용하여 Native Mobile App에서 사용할 수 있는 __CAPGO_KEEP_0__ 페이지를 Wrap routed pages in __CAPGO_KEEP_0__ Native Mobile App에서 사용할 수 있는 __CAPGO_KEEP_0__ Capacitor API를 사용하여 Native Mobile App에서 사용할 수 있는 __CAPGO_KEEP_0__ 페이지를 Wrap routed pages in __CAPGO_KEEP_0__ Native Mobile App에서 사용할 수 있는 __CAPGO_KEEP_0__ Capacitor API를 사용하여 Native Mobile App에서 사용할 수 있는 __CAPGO_KEEP_0__ 페이지를 Wrap routed pages in __CAPGO_KEEP_0__ Native Mobile App에서 사용할 수 있는 __CAPGO_KEEP_0__ Capacitor API를 사용하여 Native Mobile App에서 사용할 수 있는 __CAPGO_KEEP_0__ 페이지를 Wrap routed pages in __CAPGO_KEEP_0__ Native Mobile App에서 사용할 수 있는 __CAPGO_KEEP_0__ Capacitor API를 사용하여 Native Mobile App에서 cap-router-outlet, cap-page, 및 cap-content, 그리고 호출 setDirection('forward') 또는 setDirection('back') 새로운 기능에 작업하기 전에 논의하고 이슈를 만들고 있습니다. router.push() 또는 router.back()웹 헤더나 푸터를 네이티브 네비게이션 소유하는 표면에서 중복하지 마십시오.
See the full guides: Capgo를 사용하여 @capgo/capacitor-네이티브 네비게이션을 빌드합니다. 및 @capgo/capacitor-transitions.
안전 영역
Tailwind CSS에서 장치 안전 영역을 사용하려면 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__에서 발표됨) tailwind-capacitor npm가 친화적인 Tailwind 플러그인으로 제공하는 유틸리티 및 기타 기능 safe-areas utilities and other Capacitor-friendly Tailwind plugins:
bun add -D tailwind-capacitor
Tailwind의 유틸리티를 사용하여 styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";
, pt-safe, pb-safe대신 px-safe 및 env(safe-area-inset-*) Next.js와 Capacitor를 사용하여 네이티브 모바일 앱을 빌드하는 방법 Next.js 설정에 필요한 항목이 누락된 경우 GitHub에 PR을 열어보세요.
iOS 레이아웃 문제를 해결하는 방법 (뷰포트, 안전 영역, 가로 스크롤)
iOS에서 콘텐츠가 잘려나거나-shifted되거나 가로 스크롤이 가능하다면, 더 많은 overflow-x: hidden 또는 뷰포트 태그만 조정하는 것만으로는 문제를 해결할 수 없습니다. 이러한 체크를 순서대로 진행하세요.
뷰포트 메타 태그가 올바르게 적용되었는지 확인하세요
App Router (app/export) viewport from app/layout.tsx:
import type { Viewport } from 'next';
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
viewportFit: 'cover',
};
Pages Router (pages/뷰포트 메타 태그를 pages/_app.tsx, 아닌 _document.tsx (Next.js는 뷰포트 동작에 대한 태그를 기대하는 방식으로 적용하지 않을 수 있습니다.) _document.tsx iOS 안전 영역을 처리하려면 루트 wrapper에서만 한 번에 처리해야 합니다.
싱글 앱 셸을 만들고 안전 영역 패딩을 거기에 적용하세요 — 여러 개의 중첩된 컴포넌트에서 적용하지 마세요:
모든 페이지 콘텐츠를 내부에 감싸세요.
html,
body,
#__next {
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);
}
안전 영역 패딩이 중복되어 헤더, 모달, 레이아웃 wrapper에서 UI가 잘린 것처럼 보이거나 너무 크게 보이는 경우가 있습니다. .app-shell그리고 @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__를 사용하여 같은 패딩을 표현할 수 있습니다.
싱글 셸에 패딩을 적용할 수 있는 유틸리티를 사용할 수 있습니다. iOS capgo를 capacitor로 설정하세요.역할: 짧은 UI 레이블 또는 네비게이션 아이템. 메시지 키 `live_update_dynamic_label_to` (Live Update Dynamic Label To). pt-safe pb-safe px-safe 페이지/영역: 라이브 업데이트 제품 페이지.
Set Capacitor iOS contentInset 메시지 키 `live_update_dynamic_label_to` (Live Update Dynamic Label To). never first
In capacitor.config.ts, native UI를 사용하고 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 padding을 혼합하는 것은 일반적인 double spacing의 원인입니다. env(safe-area-inset-*) 실제로 오버플로우가 발생하는 요소를 찾으세요
일반적으로 원인은
, Tailwind 100vw, 고정 픽셀 너비를 사용하는 요소, 또는 w-screenSafari Web Inspector에서 실행하세요: min-width.
Tailwind를 사용하여
[...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,
}));
__CAPGO_KEEP_0__를 교체하세요 w-screen Next.js와 Capacitor를 사용하여 네이티브 모바일 앱을 빌드하는 방법 w-full 가능한 경우에만 사용합니다. 많은 수평 방향으로의 오버플로우 문제는 duplicated safe-area padding, 또는 고정 너비 컨테이너에서 오는 것이 아니라 viewport meta 태그 자체에서 오는 것입니다. 100vw / w-screen성능 최적화
Next.js와 Capgo 앱의 최적 성능을 보장하기 위해 다음의 최적화 방법을 고려해 보세요.
To ensure optimal performance of your Next.js and Capacitor app, consider the following best practices:
- 이미지 및 기타 미디어 파일을 최적화하여 로딩 시간을 줄이세요.
- 컴포넌트 및 페이지의 초기 로드 성능을 개선하기 위해 지연 로딩을 구현하세요.
- Next.js와 함께 서버 사이드 렌더링 (SSR)을 사용하여 앱의 로딩 속도와 검색 엔진 최적화 (SEO)를 향상하세요.
- Capgo의 내장 최적화 기능, 예를 들어 웹 뷰 캐싱 및 앱 번들링을 활용하세요.
- Leverage Capacitor’s built-in optimizations, such as web view caching and app bundling.
Capgo 8을 사용하여 기존의 Next.js 웹 애플리케이션을 네이티브 iOS 및 Android 앱으로 성공적으로 변환했습니다. 웹 코드베이스는 이제 모바일 장치에서 작동하며 장치 API에 접근할 수 있습니다.
You’ve successfully converted your existing Next.js web application into native iOS and Android apps using Capacitor 8. Your web codebase now runs natively on mobile devices with access to device APIs.
성취한 것:
- Next.js를 정적 내보내기 위해 구성했습니다.
- Capacitor 8에 필수 플러그인을 추가했습니다.
- iOS 및 Android 시뮬레이터로 빌드 및 배포했습니다.
- 개발 중에 라이브 리로드를 활성화했습니다.
- 일반적인 iOS 레이아웃 문제(뷰포트, 안전 영역, 오버플로)를 해결했습니다.
- Capgo Native Navigation 및 Transitions를 사용하여 네이티브 느낌의 UI를 추가했습니다.
다음 단계:
- 설정 Capgo 앱 스토어 재제출 없이 오버 더 에어 업데이트
- 카메라, 위치 정보, 푸시 알림과 같은 네이티브 플러그인을 더 추가하세요
- 프로덕션에 대한 앱 아이콘 및 스플래시 화면을 구성하세요.
- 앱 스토어 및 구글 플레이 제출을 위해 앱을 준비하세요.
새로운 프로젝트를 시작하고 싶으세요? Next.js 모바일 앱을 처음부터 만들기 가이드된_walkthrough를 확인하세요.
자원
- Next.js 문서
- @capgo/capacitor-native-navigation — Liquid Glass 탭 바 및 네이티브 크롬
- Capacitor 8 문서
- @capgo/capacitor-transitions — 네이티브한 느낌의 페이지 전환
- @capgo/tailwind-capacitor — Tailwind safe-area utilities for Capacitor
- Capgo - Live Updates for Capacitor Apps
Learn how Capgo can help you build better apps faster, 회원가입을 위해 무료 계정으로 가입하세요. 오늘 가입하세요.
Convert Your Next.js App to iOS & Android with Capacitor 8
Next.js 앱을 iOS 및 Android로 변환하는 __CAPGO_KEEP_0__ 8 Next.js 앱을 iOS 및 Android로 변환하는 Capacitor 8을 사용하는 경우 Next.js 앱을 iOS 및 Android로 변환하는 __CAPGO_KEEP_0__ 8을 사용하여 Native 플러그인 작업을 계획할 때 Capgo 플러그인 디렉토리와 연결하세요. Capgo 플러그인 디렉토리에서 제품 워크플로우 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부 사항 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항 아이오닉 엔터프라이즈 플러그인 대안 아이오닉 엔터프라이즈 플러그인 대안의 제품 워크플로우 Capgo 네이티브 빌드 Capgo 네이티브 빌드의 제품 워크플로우