将您的 Nuxt 应用转换为 iOS & Android 与 Capacitor 8

Introduction

如果您已经有一个 Nuxt 网站应用？本指南将教您如何将其转换为原生 iOS 和 Android 移动应用使用 Capacitor 8 — 性能更好、功能更新的最新版本。

Capacitor 将您的 web 应用包裹在原生容器中，给您访问设备 API（如摄像头、文件系统和推送通知）的机会，同时保留您的现有 Vue 代码库。与 Flutter 或 React Native 不同，您不需要重写任何内容 —您的 Nuxt code 将保持不变。

您将学习：

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

想从零开始一个新项目？查看我们的关于从零开始构建 Nuxt 移动应用.

使用 Nuxt 的好处和 Capacitor

Code 可复用性: 将 Vue 组件和逻辑分享到 web 和移动应用之间。
性能: Nuxt 的静态生成创建了优化的包，适合移动设备。
原生功能: 通过 Capacitor 插件访问设备功能，如摄像头、地理位置和文件系统。
简化开发: 使用熟悉的 Vue/Nuxt 模式而无需学习原生开发。

前置条件

在开始之前，请确保你已经安装了:

Node.js 18+ 已安装
一个现有的 Nuxt 4 应用
Xcode (仅限macOS，用于iOS开发)
Android Studio (仅限Android开发)

配置您的Nuxt应用程序以支持移动

配置您的Nuxt应用程序的第一步是静态生成。 Capacitor 需要将静态HTML/JS/CSS文件打包到原生应用中。

确保你的 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"
  }
}

重要提示： 如果你正在使用服务器端功能（API 路由，服务器中间件等），你需要将这些功能重构为使用客户端替代品或外部 API。

通过运行来测试静态生成：

bun run generate

你应该看到一个 .output/public 文件夹包含你的静态文件。这就是 Capacitor 将打包到你的原生应用中的内容。

Adding Capacitor 8 to Your Project

将你的 Nuxt 应用打包到原生移动容器中，按照以下步骤操作：

Install Capacitor core and CLI:

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

Install common Capacitor plugins you’ll likely need:

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

这些插件提供了基本功能：

@capacitor/app: 处理应用程序生命周期事件 (前台/后台, 深度链接)
@capacitor/keyboard: 在移动设备上控制键盘行为
@capacitor/splash-screen: 管理原生启动屏幕
@capacitor/status-bar: 美化设备状态栏
@capacitor/preferences: 键值存储 (类似 localStorage 但原生)

初始化 Capacitor 以及您的项目详细信息:

bunx cap init my-app com.example.myapp --web-dir .output/public

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

添加本机平台文件夹：

bunx cap add ios
bunx cap add android

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

要构建Android项目，您需要 Android Studio。对于iOS，您需要一台Mac电脑。 Xcode.

构建和同步您的项目：

bun run mobile

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

构建和部署原生应用

要构建和部署您的原生移动应用，请遵循以下步骤：

要开发 iOS 应用，您需要安装 Xcode ，而要开发 Android 应用，您需要安装 Android Studio 。此外，如果您打算在应用商店上发布您的应用，则需要为 iOS 注册 Apple Developer Program，和为 Android 注册 Google Play Console。

打开原生项目：

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-run

在 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;

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

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

bunx cap copy

命令将web文件夹和配置更改复制到原生项目中，而不更新整个项目。 copy 在Nuxt开发服务器中启动并在Xcode/Android Studio中重建：

__CAPGO_KEEP_0__

bun run dev

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

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

使用 Capacitor 插件

Capacitor 插件使您能够从 Nuxt 应用程序访问原生设备功能。让我们探索如何使用分享插件作为示例：

安装分享插件：

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布局问题，例如水平溢出或裁剪安全区域。

我已经多年来与Ionic一起工作， Ionic 来构建跨平台应用，但将其与Nuxt集成是hacky且不值得的，尤其是当你已经有 Tailwind CSS.

要在Nuxt + Capacitor应用中实现原生移动感知，使用Capgo插件代替仅限Web的UI套件，如Konsta UI：

@capgo/capacitor-native-navigation —原生导航栏，iOS上的液态玻璃标签栏，以及Android上的模糊标签栏样式。你的Nuxt路由保持路由状态；插件拥有原生浏览器。
@capgo/capacitor-transitions —在WebView层中实现Ionic风格的页面过渡和iOS边缘滑动返回，且不需要采用Ionic UI。

安装双方:

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

在应用壳中添加原生页面过渡:

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

将路由页面包裹在 cap-router-outlet, cap-page,和 cap-content,并调用 setDirection('forward') 或 setDirection('back') 前导航。不要在原生导航拥有这些表面的情况下重复 web 头部或底部。

参见完整指南: 使用 @capgo/capacitor-native-navigation 和使用 @capgo/capacitor-transitions.

安全区域使用 Tailwind

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

bun add -D tailwind-capacitor

在 app/assets/css/main.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

对于使用 Tailwind CSS 4 的 Nuxt 4，务必将此导入放在 CSS 文件中引用的位置： nuxt.config.ts.

使用类似 pt-safe, pb-safe和 px-safe 的实用程序代替在各处使用 env(safe-area-inset-*) by hand. 该项目正在积极开发中 — 如果您的 Nuxt 设置中缺少什么东西, 在 GitHub 上打开一个 PR.

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

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

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

在 nuxt.config.ts中设置视口 app.head:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        {
          name: 'viewport',
          content: 'width=device-width, initial-scale=1, viewport-fit=cover',
        },
      ],
    },
  },
});

从根包装器中处理 iOS 安全区域

创建一个单独的应用程序 shell 并在其中应用安全区域填充 — 不要在多个嵌套组件中进行：

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 看起来被裁剪或过大。

使用 @capgo/tailwind-capacitor,您可以使用类似 pt-safe pb-safe px-safe 的工具来表示相同的填充

Set Capacitor iOS `contentInset` 设置 __CAPGO_KEEP_0__ iOS `never` 到

首先 capacitor.config.ts在 contentInsetMode: 'css',优先使用原生边距禁用并让 CSS (或 Native Navigation 的)

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) 混合 __CAPGO_KEEP_0__ 的自动内容内边距与 CSS

找到真正的溢出元素

通常的罪魁祸首是使用 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, 重复的安全区域填充, 或一个固定宽度容器 — 而不是来自视口元标签本身。

结论

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

您实现了什么:

配置了 Nuxt 以及静态生成
添加了 Capacitor 8 以及必需的插件
构建并部署到 iOS 和 Android 模拟器
为开发启用了实时重载
解决了常见的 iOS 布局问题（视口、安全区域、溢出）
添加了 Capgo Native Navigation 和 Transitions 以实现原生感觉的 UI

下一步：

设置 Capgo 用于在应用商店重新提交之前进行无线更新
添加更多原生插件，如摄像头、地理位置或推送通知
配置应用图标和启动屏幕以适应生产环境
为 App Store 和 Google Play 提交做好准备

新项目从头开始？看看从零开始构建 Nuxt 移动应用来一步一步的指引。

资源

Nuxt 文档
Capacitor 8 文档
@capgo/capacitor-native-navigation — Liquid Glass tab bar 和原生浏览器
@capgo/capacitor-transitions — 原生感觉的页面过渡
@capgo/tailwind-capacitor — Capacitor 安全区域工具
Capgo - Live Updates for Capacitor Apps

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

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

如果您正在使用 使用 Capacitor 8 计划原生插件工作，连接它到 __CAPGO_KEEP_0__ 插件目录 Capgo 插件目录中的产品工作流程 Capgo 由 __CAPGO_KEEP_1__ 提供的插件 Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, 添加或更新插件对于在添加或更新插件中实现的细节 Ionic企业插件替代品对于Ionic企业插件替代品中的产品工作流程 Capgo原生构建对于Capgo原生构建中的产品工作流程

使用 Capacitor 8 将您的 Nuxt 应用程序转换为 iOS & Android

Introduction

使用 Nuxt 的好处和 Capacitor

前置条件

配置您的Nuxt应用程序以支持移动

Adding Capacitor 8 to Your Project

构建和部署原生应用

Capacitor Live Reload

使用 Capacitor 插件

原生感知UI，使用Capgo原生导航和过渡

安全区域使用 Tailwind

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

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

从根包装器中处理 iOS 安全区域

Set Capacitor iOS `contentInset` 设置 __CAPGO_KEEP_0__ iOS `never` 到

找到真正的溢出元素

结论

资源

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

使用 Capacitor 8 将您的 Nuxt 应用程序转换为 iOS &amp; Android

Introduction

使用 Nuxt 的好处和 Capacitor

前置条件

配置您的Nuxt应用程序以支持移动

Adding Capacitor 8 to Your Project

构建和部署原生应用

Capacitor Live Reload

使用 Capacitor 插件

原生感知UI，使用Capgo原生导航和过渡

安全区域使用 Tailwind

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

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

从根包装器中处理 iOS 安全区域

Set Capacitor iOS contentInset 设置 __CAPGO_KEEP_0__ iOS never 到

找到真正的溢出元素

结论

资源

继续使用 Capacitor 8 将您的 Nuxt 应用转换为 iOS &amp; Android

使用 Capacitor 8 将您的 Nuxt 应用程序转换为 iOS & Android

Set Capacitor iOS `contentInset` 设置 __CAPGO_KEEP_0__ iOS `never` 到

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