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

Introduction

如果您已经有一个Next.js web应用？本指南将教您如何将其转换为原生iOS和Android移动应用使用 Capacitor 8 — 最新版本，性能和新功能改进。

Capacitor 将您的web应用包装在一个原生容器中，给您访问设备API，如摄像头、文件系统和推送通知的机会，同时保留您的现有React代码库。与React Native不同，您不需要重写任何内容 ——您的Next.js code 将按原样运行。

您将学到：

配置您的现有Next.js应用程序以静态导出
添加 Capacitor 8 以便本机插件
在iOS和Android模拟器上构建和测试
启用快速开发的实时重载
可选添加Konsta UI以原生样式的组件

想从头开始一个新项目？请查看我们的指南在 Scratch 中构建下一代移动应用.

使用 Next.js 和 Capacitor 的好处

Code 的可重用性：Next.js 允许您编写可重用的组件并在您的 Web 和移动应用之间共享 code，节省开发时间和精力。
性能：Next.js 提供内置的性能优化功能，例如服务器端渲染和 code 分割，确保快速加载时间和smooth 用户体验。
原生功能： Capacitor 提供对原生设备功能的访问，例如相机、地理位置等，允许您构建功能丰富的移动应用。
简化的开发：使用 Capacitor，您可以使用熟悉的 Web 技术开发和测试移动应用，降低学习曲线并简化开发过程。

先决条件

：在开始之前，请确保您有：

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

替换 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 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。

打开原生项目：

For iOS:

bun run mobile:ios

For 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 __CAPGO_KEEP_0__

使用 Android Studio 或 Xcode 在设备上重建并运行应用程序。

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

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

使用 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

Or just sync without rebuilding:

bunx cap sync

Rebuild and run the app on your device.

现在，当你点击“立即分享”按钮时，原生分享对话框会出现，允许你分享内容到其他应用中。

为了让按钮看起来更适合移动端，我们可以使用我最喜欢的UI组件库Next.js（无意中）添加一些样式。

添加Konsta UI v5和Tailwind CSS 4

我已经多年来 Ionic 用它来构建跨平台应用，曾经是最佳选择。但是现在我不再推荐它了，因为它很难与Next.js集成，而且不值得当你已经有 Tailwind CSS 4.

了，想要一个真正棒的适应iOS和Android特定样式的移动端UI，我推荐使用Konsta UI v5。

你需要有 Tailwind CSS 4 已经安装为了增强你的 Next.js 应用程序的移动端 UI， Konsta UI v5,一个适应 iOS 和 Android 风格的移动端 UI 组件库。按照以下步骤来集成 Konsta UI v5：

安装所需的包（Konsta UI v5）：

bun add konsta

在你的主 CSS 文件中导入 Konsta UI 主题（例如 styles/globals.css):

@import 'tailwindcss';
/* import Konsta UI v5 theme */
@import 'konsta/theme.css';

配置 Tailwind CSS 4 for Next.js (PostCSS):

在项目根目录创建: postcss.config.mjs Tailwind v4 使用 PostCSS 直接在 Next.js 中。保持你的全局导入在

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

(已经在上面添加过了) styles/globals.css 将你的应用程序包裹在 Konsta UI v5 中

__CAPGO_KEEP_0__ App 组件 pages/_app.js:

import { App } from 'konsta/react';
import '../styles/globals.css';

function MyApp({ Component, pageProps }) {
  return (
    <App theme="ios">
      <Component {...pageProps} />
    </App>
  );
}

export default MyApp;

示例页面

现在设置完成后，我们可以在 Next.js 页面中使用 Konsta UI v5 React 组件。

更新 pages/index.js 文件以使用 Konsta UI v5 组件：

import {
  Page,
  Navbar,
  Block,
  Button,
  List,
  ListItem,
  BlockTitle,
} from 'konsta/react';

export default function Home() {
  return (
    <Page>
      <Navbar title="My App" />

      <Block strong>
        <p>
          Here is your Next.js & Konsta UI app. Let's see what we have here.
        </p>
      </Block>
      <BlockTitle>Navigation</BlockTitle>
      <List>
        <ListItem href="/about/" title="About" />
        <ListItem href="/form/" title="Form" />
      </List>

      <Block strong className="flex space-x-4">
        <Button>Button 1</Button>
        <Button>Button 2</Button>
      </Block>
    </Page>
  );
}

添加 Roboto 字体以支持 Material Design 主题（Konsta UI v5 必须）：

在你的 pages/_document.js 或主 HTML 文件中添加：

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,500;0,700;1,400;1,500;1,700&display=swap"
  rel="stylesheet"
/>

重启开发服务器并重建应用。

您的 Next.js 应用程序现在应该具有由 Konsta UI v5 和 Tailwind CSS 4 风格化的原生移动 UI 支持。

性能优化

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

通过移除未使用的依赖项和资产来最小化应用程序大小。
优化图像和其他媒体文件以减少加载时间。
为组件和页面实现懒加载，以改善初始加载性能。
使用 Next.js 的服务器端渲染（SSR）来增强应用程序的加载速度和搜索引擎优化（SEO）。
利用 Capacitor 的内置优化功能，例如 WebView 缓存和应用程序打包。

结论

您已成功将现有 Next.js 网站应用程序转换为使用 Capacitor 8 的原生 iOS 和 Android 应用程序。您的 Web 代码库现在可以在移动设备上以原生方式运行，具有对设备 API 的访问权限。

您实现了什么：

配置 Next.js 以进行静态导出
添加 Capacitor 8 以及必需的插件
在 iOS 和 Android 模拟器上构建并部署
为开发启用实时重载
可选添加 Konsta UI 以获得原生样式的组件

下一步骤：

设置 Capgo 无需重新提交应用商店即可实现 OTA 更新
添加更多原生插件，如摄像头、地理位置或推送通知
配置应用图标和启动屏幕以便生产
为 App Store 和 Google Play 提交应用做好准备

要开始一个全新的项目？请查看从零开始构建一个 Next.js 移动应用了解一步一步的指引

资源

了解如何使用 Capgo 快速高效地构建应用免费注册今天

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

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

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