将您的Nuxt应用转换为iOS和Android应用程序,Capacitor 8

介绍

您有一个现有的 Nuxt 网站应用程序吗？在本指南中，您将学习如何使用 __CAPGO_KEEP_0__ 将其转换为原生 iOS 和 Android 移动应用程序。 Capacitor 8 — 性能和新功能的最新版本

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

您将学习：

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

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

使用 Nuxt 和 Capacitor 的好处

Code 可重用性: 在 Web 和移动应用之间共享 Vue 组件和逻辑。
性能: 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 将打包到您的原生应用中的内容。

将 Capacitor 8 添加到您的项目中

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

安装 Capacitor 核心和 CLI:

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

安装常见的 Capacitor 插件：

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

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

@capacitor/app: 处理应用程序生命周期事件（前台/后台，深度链接）
@capacitor/keyboard: 在移动设备上控制键盘行为
@capacitor/启动屏幕:管理原生启动屏幕
@capacitor/状态栏:样式设备状态栏
@capacitor/偏好设置:原生键值存储（类似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

对于Android：

bun run mobile:android

或直接使用Capacitor CLI：

bunx cap open ios
bunx cap open android

构建并运行应用：

android-studio-run

在 Android Studio 中，等待项目准备好，然后点击“运行”按钮将应用程序部署到连接的设备或模拟器中。

xcode-run

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

恭喜！您已成功将 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 中重建：

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

bun run dev

注意：

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

Using Capacitor Plugins

Capacitor 插件使您能够从 Nuxt 应用程序访问本机设备功能。让我们探索如何使用"Share"插件作为示例： Share 插件作为示例：

安装 Share 插件：

bun add @capacitor/share

创建或更新一个页面来使用 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 为了在 Nuxt 中构建跨平台应用，但将其与 Nuxt 集成起来是hacky的，并且当您已经有它时，很少值得 Tailwind CSS.

在 Nuxt + Capacitor 应用中，使用 Capgo 插件来实现原生移动体验，而不是像 Konsta UI 这样的仅限 web UI 套件：

@capgo/capacitor-native-navigation — 原生导航栏、iOS Liquid Glass tab bar 和 Android 模糊 tab bar 风格。您的 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 bar（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-原生导航和使用@capgo/capacitor-过渡.

安全区域与Tailwind

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

bun add -D tailwind-capacitor

在 app/assets/css/main.css:

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

对于使用 Nuxt 4 和 Tailwind CSS 4 的开发者，务必在 CSS 文件中保留以下导入语句： nuxt.config.ts.

使用工具类，如 pt-safe, pb-safe，和 px-safe 代替手动 env(safe-area-inset-*) 。该项目正在积极开发中 — 如果您的 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安全区域

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

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 的工具来表示相同的填充。

设置 Capacitor iOS `contentInset` 为 `never` 首选

在 capacitor.config.ts，优先使用原生 inset disabled 并让 CSS (或 Native Navigation 的) contentInsetMode: 'css'控制安全区域：

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

混合 Capacitor 自动内容 inset 与 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,重复的安全区域填充，或者一个固定宽度的容器 —— 不是来自视口元标签本身。

结论

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

您完成了什么：

配置 Nuxt 以静态生成
添加 Capacitor 8 以及必需的插件
在 iOS 和 Android 模拟器上构建并部署
为开发启用实时重载
解决了常见的 iOS 布局问题（视口、安全区域、溢出）
添加了具有本机感觉的 UI，使用 Capgo 本机导航和过渡

下一步骤：

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

正在启动一个全新的项目？请参阅从零开始构建 Nuxt 移动应用以指导式教程的形式进行

资源

Nuxt 文档
Capacitor 8 文档
@capgo/capacitor-native-navigation — Liquid Glass tab bar 和原生浏览器
@capgo/capacitor-transitions — 原生感知页面过渡
@capgo/tailwind-capacitor — Tailwind safe-area utilities for Capacitor
Capgo - Live Updates for Capacitor Apps

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

从 Convert Your Nuxt App to iOS & Android with Capacitor 8 开始

如果您正在使用 使用 Convert Your Nuxt App to iOS & Android with Capacitor 8 为了计划原生插件工作，连接它与 Capgo Plugin Directory 在 Capgo Plugin Directory 中的产品工作流程由 Capgo 提供的 Capacitor Plugins 在由 Capgo 提供的 Capacitor Plugins 中的实现细节添加或更新插件在添加或更新插件中实现的细节 Ionic Enterprise Plugin 的替代方案对于Ionic Enterprise插件替代品的产品工作流程 Capgo原生构建对于Capgo原生构建的产品工作流程

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

介绍

使用 Nuxt 和 Capacitor 的好处

前置条件

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

将 Capacitor 8 添加到您的项目中

构建和部署原生应用

Capacitor Live Reload

Using Capacitor Plugins

本机感知 UI 与 Capgo 本机导航和过渡

安全区域与Tailwind

解决 iOS 布局问题（视口、安全区域和水平溢出）

确保视口元标签正确应用

从根组件中只处理iOS安全区域

设置 Capacitor iOS `contentInset` 为 `never` 首选

找到真正溢出的元素

结论

资源

从 Convert Your Nuxt App to iOS & Android with Capacitor 8 开始

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

介绍

使用 Nuxt 和 Capacitor 的好处

前置条件

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

将 Capacitor 8 添加到您的项目中

构建和部署原生应用

Capacitor Live Reload

Using Capacitor Plugins

本机感知 UI 与 Capgo 本机导航和过渡

安全区域与Tailwind

解决 iOS 布局问题（视口、安全区域和水平溢出）

确保视口元标签正确应用

从根组件中只处理iOS安全区域

设置 Capacitor iOS contentInset 为 never 首选

找到真正溢出的元素

结论

资源

从 Convert Your Nuxt App to iOS &amp; Android with Capacitor 8 开始

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

设置 Capacitor iOS `contentInset` 为 `never` 首选

从 Convert Your Nuxt App to iOS & Android with Capacitor 8 开始