使用 Capacitor 8 将您的 Next.js 应用转换为 iOS 和 Android

介绍

您有一个现有的 Next.js 网站应用程序吗？本指南将教您如何使用 __CAPGO_KEEP_0__ Capacitor 8 — 性能更好、功能更新的最新版本

Capacitor 将您的 web 应用程序包装在一个本机容器中，给您访问设备 API 的权限，如相机、文件系统和推送通知，而不改变您的现有 React 代码库。与 React Native 不同，您不需要重写任何内容 ——您的 Next.js code 将保持不变。

您将学到：

配置您的现有 Next.js 应用程序以静态导出
添加 Capacitor 8 以使用基本的本机插件
在 iOS 和 Android 模拟器上构建和测试
启用快速开发的实时重载
解决常见的 iOS 布局问题（视口、安全区域、水平溢出）
添加本机感知的 UI 以使用 Capgo Native Navigation 和 Transitions

想从头开始一个新项目？检查我们的指南《从头开始构建一个 Next.js 移动应用程序.

使用 Next.js 和 Capacitor 的好处

Code 可重用性: Next.js enables you to write reusable components and share code between your web and mobile apps, saving development time and effort.
性能优化: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
原生功能: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
简化开发: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.

前置条件

在开始之前，请确保您已经:

Node.js 18+ 已安装
已有 Next.js 15+ 应用
Xcode (仅限 macOS,用于 iOS 开发)
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;

The output: 'export' 设置告诉 Next.js 生成静态 HTML 文件，并 images: { unoptimized: true } 绕过 Next.js 图像优化，这需要一个服务器。

重要： 如果您正在使用需要服务器的功能（API 路由，带有数据获取的服务器组件等），则需要将其重构为使用客户端替代品或外部 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 文件夹在您的项目根目录中。这包含了所有的静态文件，Capacitor 将打包到您的原生应用中。

将 Capacitor 8 添加到您的项目中

将您的 Next.js 应用打包到原生移动容器中，请遵循以下步骤：

安装 Capacitor 核心和 CLI:

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

安装常见的 Capacitor 插件，您可能需要：

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferences

这些插件提供基本功能：

@capacitor/app: 处理应用程序生命周期事件（前台/后台，URL）
@capacitor/keyboard: 在移动设备上控制键盘行为
@capacitor/splash-screen: 管理原生启动屏幕
@capacitor/preferences: 持久存储键值数据

初始化Capacitor：

bunx cap init my-app com.example.myapp --web-dir out

将__CAPGO_KEEP_0__替换为您的应用程序名称 my-app 将__CAPGO_KEEP_0__替换为您的应用程序名称 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 android

Capacitor 将在您的项目根目录中创建 ios 和 android 文件夹，包含本机项目。

要构建 Android 项目，您需要 Android Studio。对于 iOS，您需要一台带有 Xcode.

构建和同步您的项目：

bun run mobile

此命令会运行您的自定义脚本，构建 Next.js 项目并同步静态文件到原生平台。

构建和部署原生应用

要构建和部署您的原生移动应用，请遵循以下步骤：要开发 iOS 应用，您需要安装 Xcode ，并且要开发 Android 应用，您需要安装 Android Studio 。此外，如果您打算在应用商店上发布您的应用，则需要为 iOS 注册 Apple Developer Program，并为 Android 注册 Google Play Console。

打开原生项目：

iOS：

bun run mobile:ios

Android：

bun run mobile:android

或直接使用 Capacitor CLI:

bunx cap open ios
bunx cap open android

Build and run the app:

android-studio-run

在 Android Studio 中，等待项目准备好，然后点击“运行”按钮将应用部署到连接的设备或模拟器中。
在 Xcode 中，设置您的签名账户以将应用部署到真实设备。如果您以前没有这样做过，Xcode 将指导您完成此过程（请注意，您需要在 Apple Developer Program 中注册）。一旦设置好，点击“播放”按钮即可在连接的设备上运行应用。

恭喜您！您已成功将 Next.js 网站应用部署到移动设备。

但请稍等，开发期间还有更快的方法……

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: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
};

export default config;

将 YOUR_IP_ADDRESS 替换为您的本地 IP 地址（例如 192.168.1.100).

将更改应用到您的原生项目：

bunx cap copy

命令将 web 文件夹和配置更改复制到原生项目，而不更新整个项目。 copy 使用 Android Studio 或 Xcode 在设备上重建并运行应用。

现在，无论您对 Next.js 应用程序进行哪些更改，移动应用程序都会自动重新加载以反映这些更改。

注意：如果您安装新插件或更改原生文件，则需要重建原生项目，因为实时重新加载仅适用于 web __CAPGO_KEEP_0__ 更改。

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.

使用 Capacitor 插件

Capacitor 插件允许您从您的 Next.js 应用程序访问本机设备功能。让我们探索如何使用分享插件作为示例：

安装分享插件：

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

重新构建并在设备上运行应用程序。

现在，当您点击“立即分享！”按钮时，会出现本机分享对话框，允许您与其他应用程序共享内容。

下一步，您可以让应用在iOS和Android上感觉更像原生应用，使用Capgo导航和过渡，并解决常见的iOS布局问题，例如水平溢出或裁剪安全区域。 ## 原生UI体验使用Capgo原生导航和过渡

我已经工作了几年， Ionic 来构建跨平台应用，但将其与Next.js集成起来很hacky，并且很少值得在您已经有 Tailwind CSS 4.

的情况下进行。为了在Next.js + Capacitor应用中实现原生移动体验，使用Capgo插件代替像Konsta UI这样的仅限Web UI套件：

@capgo/capacitor-native-navigation — 原生导航栏，iOS上的液态玻璃式标签栏，以及Android上的模糊标签栏样式。您的Next.js路由器保留路由状态；插件拥有原生浏览器。
@capgo/capacitor-transitions — 在WebView层中实现Ionic样式页面过渡和iOS边缘滑动返回，

Install both:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

使用 CSS inset 模式配置原生导航，使 web 内容尊严原生导航条:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

渲染 Liquid Glass tab 条 (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' });

将路由页面包裹在 cap-router-outlet, cap-page,和 cap-content,并调用 setDirection('forward') 或 setDirection('back') 前 router.push() 或 router.back(). 在原生导航拥有导航条或底部区域时，不要重复 web 头部或底部区域。

查看完整指南: 使用 @capgo/capacitor-native-navigation 和使用 @capgo/capacitor-转换.

安全区域

在 Tailwind CSS 中使用设备安全区域，请使用 @capgo/tailwind-capacitor (已发布于 tailwind-capacitor npm）。它提供 safe-areas 实用程序和其他 Capacitor-友好的 Tailwind 插件：

bun add -D tailwind-capacitor

在 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 配置缺少某些内容, 在 GitHub 上打开一个 PR.

修复 iOS 布局问题 (视口、安全区域和水平溢出)

如果内容在 iOS 上被裁切、偏移或水平滚动, overflow-x: hidden 或仅仅调整视口标签通常无法解决问题。按照以下顺序检查这些问题。

确保视口元标签已正确应用

App Router (app/): 从 viewport Pages Router app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

): 将视口元标签放在 (pages/, 不 pages/_app.tsxtargetLanguage _document.tsx (Next.js可能不会像您期望的那样为视口行为应用标签). _document.tsx 从一个根包装器中只处理iOS安全区域

创建一个单独的应用程序外壳并在其中应用安全区域填充，而不是在多个嵌套组件中：

将所有页面内容包装在

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);
}

.在头部、模态对话框和布局包装器中重复的安全区域填充通常会使UI看起来被裁剪或过大。 .app-shell使用

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitor的工具表达相同的填充。 pt-safe pb-safe px-safe 将__CAPGO_KEEP_0__ iOS

Set Capacitor iOS `contentInset` to `never` 首先

在使用原生导航时， capacitor.config.tsprefer native inset disabled and let CSS (或 Native Navigation’s contentInsetMode: 'css') own the safe area：

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  ios: {
    contentInset: 'never',
  },
};

混合Capacitor的自动内容内边距与CSS env(safe-area-inset-*) padding 是双倍间距的常见原因。

找到真正溢出的元素

通常的凶手是使用 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性能优化

确保您的 Next.js 和 __CAPGO_KEEP_0__ 应用程序的最佳性能，考虑以下最佳实践：

To ensure optimal performance of your Next.js and Capacitor app, consider the following best practices:

优化图像和其他媒体文件以减少加载时间。
为组件和页面实现延迟加载以提高初始加载性能。
使用 Next.js 的服务器端渲染（SSR）来增强应用程序的加载速度和搜索引擎优化（SEO）。
利用 __CAPGO_KEEP_0__ 的内置优化功能，例如 Web 视图缓存和应用程序打包。
Leverage Capacitor’s built-in optimizations, such as web view caching and app bundling.

您已成功将现有的 Next.js 网站应用程序转换为使用 __CAPGO_KEEP_0__ 8 的原生 iOS 和 Android 应用程序。您的 Web 代码库现在可以在移动设备上以原生方式运行，具有访问设备 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 用于在应用商店重新提交之前进行无线更新
添加更多原生插件，如相机、地理位置或推送通知
为生产环境配置应用图标和启动屏幕
为 App Store 和 Google Play 提交做好准备

新项目从头开始？请查看从零开始构建一个 Next.js 移动应用以引导式教程的形式

资源

Next.js 文档
@capgo/capacitor-native-navigation — Liquid Glass tab bar 和原生浏览器
Capacitor 8 文档
@capgo/capacitor-transitions — 原生感知页面过渡
@capgo/tailwind-capacitor — Capacitor 安全区域工具
Capgo - Capacitor 应用实时更新

了解如何使用 Capgo 快速构建更好的应用免费注册今天

继续使用 Capacitor 8 将您的 Next.js 应用转换为 iOS & Android

如果您正在使用 使用 Capacitor 8 将您的 Next.js 应用转换为 iOS & Android 规划原生插件工作时，连接它到 Capgo 插件目录为 Capgo 插件目录中的产品工作流程 Capacitor 插件由 Capgo 提供了解 Capacitor 插件由 Capgo 的实现细节添加或更新插件了解添加或更新插件的实现细节 Ionic 企业插件替代品了解 Ionic 企业插件替代品的产品工作流程 Capgo 原生构建了解 Capgo 原生构建的产品工作流程

将您的 Next.js 应用程序转换为 Capacitor 8

介绍