소개
이미 존재하는 Next.js 웹 애플리케이션이 있나요? 이 가이드에서는 __CAPGO_KEEP_0__를 사용하여 iOS 및 Android 모바일 앱으로 변환하는 방법을 배울 것입니다. Capacitor 역할: 제목. 보존: Capgo 제품/브랜드 및 개발자 용어를 정확하게. 메시지 키 `live_update_platform_capacitor_title` (Live Update Platform Capacitor Title).
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 React codebase. Unlike React Native, you don’t need to rewrite anything — your Next.js code runs as-is.
__CAPGO_KEEP_0__는 웹 앱을 네이티브 컨테이너에 감싸고, 카메라, 파일 시스템, 푸시 알림과 같은 장치 API에 접근할 수 있도록 해주며, 기존의 React 코드베이스를 유지합니다. React Native와 달리, __CAPGO_KEEP_1__를 사용하여 Next.js 앱을 다시 작성할 필요가 없습니다.
- 학습할 내용:
- Add Capacitor 8 with essential native plugins
- __CAPGO_KEEP_0__ 8에 필수 네이티브 플러그인을 추가합니다.
- iOS 및 Android 시뮬레이터에서 빌드 및 테스트합니다.
- iOS 레이아웃 문제를 해결하세요 (뷰포트, 안전 영역, 수평 방향 오버플로우)
- Capgo Native Navigation 및 전환을 사용하여 원활한 네이티브 UI를 추가하세요
새 프로젝트를 시작하고 싶으시다면? Next.js로 모바일 앱을 처음부터 구축하는 방법.
Next.js 및 Capacitor의 이점
- Code 재사용성: Next.js는 웹 및 모바일 앱 간에 재사용 가능한 컴포넌트를 작성하고 code를 공유할 수 있으므로 개발 시간과 노력을 절약할 수 있습니다.
- 성능: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
- : Next.js는 서버 사이드 렌더링 및 __CAPGO_KEEP_0__ 스플리팅과 같은 내장 성능 최적화 기능을 제공하여 빠른 로딩 시간과MOOTH 사용자 경험을 보장합니다.: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
- : __CAPGO_KEEP_0__는 카메라, 위치 정보, 및 더 많은 네이티브 장치 기능에 접근할 수 있으므로 기능-rich 모바일 앱을 구축할 수 있습니다. : Capacitor을 사용하면, 익숙한 웹 기술을 사용하여 모바일 앱을 개발하고 테스트할 수 있습니다. 이로 인해 학습 곡선이 줄어들고 개발 프로세스가 단순화됩니다.
기본 조건
시작하기 전에 다음을 확인하세요:
- Node.js 18+ 설치
- 기존 Next.js 15+ 애플리케이션
- Xcode (iOS 개발을 위해 macOS만)
- Android Studio (Android 개발을 위해)
Next.js 모바일 앱 구성
The first step is to configure your Next.js app for static export. Capacitor needs static HTML/JS/CSS files to bundle into the native app.
Next.js 앱을 열고 next.config.js Next.js 앱을 열고 next.config.ts파일을 열고 정적 내보내기 구성 추가
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;Next.js 앱을 모바일로 구성하는 첫 번째 단계는 정적 내보내기 구성입니다. output: 'export' Next.js 앱을 모바일로 구성하는 첫 번째 단계는 정적 내보내기 구성입니다. images: { unoptimized: true } Next.js 앱을 모바일로 구성하는 첫 번째 단계는 정적 내보내기 구성입니다.
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.
Next.js 앱을 모바일로 구성하는 첫 번째 단계는 정적 내보내기 구성입니다. 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"
}
}Next.js 앱을 모바일로 구성하는 첫 번째 단계는 정적 내보내기 구성입니다.
bun run buildNative 모바일 앱을 빌드하는 방법 out 프로젝트의 루트 폴더에 폴더가 하나 보이시나요. 이 폴더에는 Capacitor이 네이티브 앱에 패키징할 모든 정적 파일이 들어 있습니다.
Capacitor 8을 프로젝트에 추가하는 방법
네이티브 모바일 컨테이너로 패키징할 수 있는 Next.js 앱을 만들려면 다음 단계를 따르세요:
- Capacitor core 및 CLI을 설치하세요:
bun add @capacitor/core
bun add -D @capacitor/cli- Capacitor의 일반적인 플러그인을 설치하세요. 이 플러그인은 일반적으로 필요합니다:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferences__CAPGO_KEEP_0__/app
- @capacitor/app__CAPGO_KEEP_0__/keyboard
- @capacitor/keyboard__CAPGO_KEEP_0__/splash-screen
- capacitor: 모바일 앱의 네이티브 스플래시 화면 관리
- @capacitor/설정: 영구적으로 키-값 데이터 저장
- 프로젝트 세부 정보와 함께 Capacitor 초기화:
bunx cap init my-app com.example.myapp --web-dir out대체 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: '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 androidCapacitor은 ios 그리고 android 프로젝트의 루트 폴더에 있는 네이티브 프로젝트 폴더
To build the Android project, you need Android Studio. For iOS, you need a Mac with Xcode.
- 프로젝트 빌드 및 동기화:
bun run mobileThis runs your custom script that builds the Next.js project and syncs the static files with the native platforms.
네이티브 앱 빌드 및 배포
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 설치되었습니다. 또한 앱을 스토어에 배포하려면 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- 앱 빌드 및 실행:
-
Android Studio에서 프로젝트가 준비되기를 기다리십시오. 그런 다음 연결된 장치 또는 에뮬레이터에 앱을 배포하기 위해 '실행' 버튼을 클릭하십시오.
-
Xcode에서 실제 장치에 앱을 배포하기 위해 서명 계정을 설정하십시오. 이 과정을 처음으로 수행하는 경우 Xcode는 프로세스를 안내하되 (Apple Developer Program에 등록해야 함을 주의하십시오) 서명 계정을 설정한 후 '재생' 버튼을 클릭하여 연결된 장치에서 앱을 실행하십시오.
축하합니다! Next.js 웹 앱을 모바일 장치에 성공적으로 배포했습니다.
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: 'out',
server: {
url: 'http://YOUR_IP_ADDRESS:3000',
cleartext: true,
},
};
export default config;를 YOUR_IP_ADDRESS 로 대체하세요: (예시) 192.168.1.100).
- 원본 프로젝트에 변경 사항을 적용하세요:
bunx cap copy명령어는 웹 폴더와 구성 변경 사항을 원본 프로젝트로 복사하고 전체 프로젝트를 업데이트하지 않습니다. copy Android Studio 또는 Xcode를 사용하여 디바이스에서 앱을 다시 빌드하고 실행하세요.
- 이제 Next.js 앱에 변경 사항을 적용할 때마다 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.
주의: 새로운 플러그인을 설치하거나 원본 파일에 변경 사항을 적용하면 원본 프로젝트를 다시 빌드해야 합니다. 왜냐하면 라이브 리로딩은 웹 변경 사항만 적용되기 때문입니다.
Note: 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 plugins allow you to access native device features from your Next.js app. Let’s explore how to use the 구성 변경 __CAPGO_KEEP_0__
- __CAPGO_KEEP_0__
bun add @capacitor/share- __CAPGO_KEEP_0__
pages/index.jsShare 플러그인을 사용하는 파일을 선택하세요:
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 을 사용하여 크로스 플랫폼 애플리케이션을 개발해 왔습니다. 그러나 Next.js.
For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- @capgo/capacitor-native-navigation — 네이티브 네비게이션 바, iOS에서 Liquid Glass 탭 바, Android에서 흐린 탭 바 스타일이 있습니다. Next.js 라우터는 경로 상태를 유지하고 플러그인은 네이티브 창을 관리합니다.
- @capgo/capacitor-transitions — WebView layer에서 Ionic-style 페이지 전환과 iOS의 에지 스와이프 백을 사용할 수 있습니다. 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}`);
});네이티브 페이지 전환을 앱 셸에 추가하세요.
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });라우팅된 페이지를 wrapping하세요. cap-router-outlet, cap-page라우팅된 페이지를 wrapping하세요. cap-contentcall setDirection('forward') 또는 setDirection('back') 전에 router.push() 또는 router.back()다음과 같은 가이드를 참조하세요:
Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation Using @capgo/capacitor-native-navigation Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions Using @capgo/capacitor-transitions.
디바이스의 안전 영역을 Tailwind CSS에서 사용하려면
@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitor __CAPGO_KEEP_0__ tailwind-capacitor Capgo의 npm)에서 사용할 수 있습니다. 그것은 safe-areas Capacitor-친화적인 Tailwind 플러그인을 포함하여
bun add -D tailwind-capacitorIn styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Next.js 앱에서 사용할 수 있는 유용한 도구 pt-safe, pb-safe, px-safe 대신 __CAPGO_KEEP_0__ env(safe-area-inset-*) 개발자가 직접 __CAPGO_KEEP_0__ open a PR on GitHub.
iOS에서 콘텐츠가 잘려나거나-shifted 또는 가로 스크롤이 가능하다면
__CAPGO_KEEP_0__ overflow-x: hidden viewport 태그를 수정하는 것만으로는 해결되지 않는다.
viewport meta 태그가 올바르게 적용되었는지 확인하십시오.
애플리케이션 라우터 (app/export viewport from app/layout.tsx:
import type { Viewport } from 'next';
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
viewportFit: 'cover',
};페이지 라우터 (pages/viewport 메타 태그를 넣어 pages/_app.tsx, 반대 _document.tsx (Next.js는 viewport 동작에 대한 태그를 기대하는 방식과 다르게 태그를 적용할 수 있습니다.) _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-shellDuplicated safe-area padding in headers, modals, and layout wrappers often makes the UI look cropped or too large.
그것과 @capgo/tailwind-capacitor그것과 함께 pt-safe pb-safe px-safe on that single 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',
},
};CSS의 패딩과 Capacitor의 자동 콘텐츠 인셋을 혼합하는 것은 두 번의 간격이 발생하는 일반적인 원인입니다. env(safe-area-inset-*) __CAPGO_KEEP_0__
실제로 넘치고 있는 요소를 찾으세요
일반적으로 범인은 픽셀 너비가 고정된 요소 또는 큰 100vwTailwind 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 태그 자체에서 오는 것이 아닙니다.
성능 최적화
To ensure optimal performance of your Next.js and Capacitor app, consider the following best practices:
- 사용되지 않는 의존성 및 자산을 제거하여 앱 크기를 최소화하세요.
- 이미지 및 다른 미디어 파일을 최적화하여 로딩 시간을 줄입니다.
- 컴포넌트 및 페이지에 대한 느긋한 로딩을 구현하여 초기 로딩 성능을 향상합니다.
- Next.js와 함께 서버 사이드 렌더링 (SSR)을 사용하여 앱의 로딩 속도와 검색 엔진 최적화 (SEO)를 향상합니다.
- Capacitor의 내장 최적화 기능을 활용하여, 예를 들어 웹 뷰 캐싱 및 앱 번들링을 사용합니다.
결론
Capacitor 8을 사용하여 기존의 Next.js 웹 애플리케이션을 iOS 및 Android 앱으로 성공적으로 변환했습니다. 웹 코드베이스는 이제 모바일 장치에서 실행되며 장치 API에 접근할 수 있습니다.
성공적으로 완료한 작업:
- Next.js를 정적 내보내기 위해 구성했습니다.
- Capacitor 8을 추가하여 필수 플러그인을 설치했습니다.
- iOS 및 Android 시뮬레이터에 빌드 및 배포했습니다.
- 개발 중에 라이브 리로드를 활성화했습니다.
- 일반적인 iOS 레이아웃 문제(뷰포트, 안전 영역, 오버플로)를 해결했습니다.
- Capgo
다음 단계:
- 설정 Capgo 앱 스토어 재제출 없이 오버 더 에어 업데이트
- 카메라, 위치 정보, 푸시 알림 등 더 많은 네이티브 플러그인을 추가하세요
- 프로덕션용 앱 아이콘과 스플래시 스크린을 구성하세요
- 앱 스토어와 구글 플레이 제출을 위해 앱을 준비하세요
새로운 프로젝트를 시작하고 싶으세요? 기본부터 시작하는 Next.js 모바일 앱을 위한 가이드 자원
__CAPGO_KEEP_0__
- Next.js Documentation
- capgo/capacitor-native-navigation — Liquid Glass tab bar and native chrome
- Capacitor 8 Documentation
- capgo/capacitor-transitions — native-feeling page transitions
- capgo/tailwind-capacitor — Tailwind safe-area utilities for Capacitor
- Capgo - Live Updates for Capacitor Apps
Next.js를 사용하여 Capgo 앱을 더 빠르게 빌드하는 방법을 알아보세요. 무료 계정으로 가입하세요. 오늘 가입하세요.
Next.js 앱을 iOS & Android로 계속 진행하세요. Capacitor 8
Next.js 앱을 iOS & Android로 변환하는 경우 Convert Your Next.js App to iOS & Android with Capacitor 8 Capacitor 플러그인을 연결하여 Native 플러그인 작업을 계획하세요. Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우 Capacitor Plugins by Capgo Capgo에서 Capacitor 플러그인 __CAPGO_KEEP_0__ 플러그인 __CAPGO_KEEP_1__에서 __CAPGO_KEEP_0__ 플러그인 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트에서 구현 세부 정보를 확인하세요. Capgo Native Builds Next.js와 Capgo을 사용하는 제품 워크플로우
