Convert Your Nuxt App to iOS & Android with Capacitor 8

介绍

您有一个现有的 Nuxt 网络应用程序？本指南将教您如何将其转换为使用 Capacitor 8 — 最新版本，性能改进和新功能

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 Vue codebase. Unlike Flutter or React Native, you don’t need to rewrite anything — your Nuxt code runs as-is.

你将学到:

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

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

使用Nuxt和Capacitor的好处

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

先决条件

: 在开始之前，请确保你有：

Node.js 18+ 已安装
一个现有的 Nuxt 4 应用
Xcode (仅限 macOS)
安卓 studio (仅限 Android)

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

首先，需要配置 Nuxt 应用程序以支持静态生成。Capacitor 需要静态 HTML/JS/CSS 文件来打包到原生应用中。

确保你的 package.json context: HTML 文本片段来自更长的 Capgo UI 字符串（父级键 `solutions_cordova_to_capacitor_ai_step2_body`）。页面/区域：Capgo 解决方案营销页面。角色：网站复制句子。见于页面 solutions/cordova-to-capacitor-ai.astro。消息键 `solutions_cordova_to_capacitor_ai_step2_body` (解决方案 Cordova 到 Capacitor AI 步骤 2 正文)。

{
  "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/应用: 处理应用程序生命周期事件（前台/后台、深度链接）
@capacitor/键盘: 在移动设备上控制键盘行为
@capacitor/启动屏幕: native启动屏幕管理
@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 项目，您需要安卓 studio。对于 iOS，您需要一台带有 Xcode.

构建和同步您的项目：

bun run mobile

这将运行您的自定义脚本，生成静态 Nuxt 构建并同步文件与本机平台。

构建和部署本机应用

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

为了开发 iOS 应用程序，您需要 Xcode 已安装，并且对于 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

构建并运行应用

安卓 studio 运行

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

xcode-run

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

恭喜！您成功部署了 Nuxt 网站应用到移动设备。

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

Capacitor 实时重载

在开发期间，您可以利用实时重载功能来实时在移动设备上看到变化。要启用此功能，请遵循以下步骤：

找到您的本地 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

该 copy 命令将复制Web文件夹和配置更改到本机项目，而不更新整个项目。

启动您的Nuxt开发服务器并在Xcode/Android Studio中重建：

bun run dev

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

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

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

重建并在设备上运行应用。

现在，当您点击“立即分享”按钮时，原生分享对话框会出现。

接下来，您可以通过 Capgo 导航和过渡使应用在 iOS 和 Android 上感觉更原生，并修复常见的 iOS 布局问题，例如水平溢出或裁切安全区域。

我已经与 ionic 为了构建跨平台应用，但将其与 Nuxt 集成起来是hacky的，并且当你已经有 Tailwind CSS.

在 Nuxt + Capacitor 应用中，为了获得原生移动体验，使用 Capgo 插件而不是像 Konsta UI 这样的仅限 web UI 套件:

@capgo/capacitor-原生导航 — 原生导航栏、Liquid Glass iOS tab栏和 Android 模糊 tab 样式。您的 Nuxt 路由器保持路由状态；插件拥有原生浏览器。
@capgo/capacitor-过渡 — 在 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') 在选择替代方案之前，

查看完整指南：使用@capgo/capacitor-原生导航和使用@capgo/capacitor-过渡.

安全区域与Tailwind

在Tailwind CSS中使用设备安全区域 @capgo/Tailwind-capacitor __CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ 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 设置中缺少某些功能，请在 __CAPGO_KEEP_0__ 上打开一个 PR 在GitHub上提交一个PR.

如果内容在 iOS 上被裁剪、偏移或水平滚动，请尝试以下步骤：

如果内容在 iOS 上被裁剪、偏移或水平滚动，请尝试以下步骤： overflow-x: hidden 如果内容在 iOS 上被裁剪、偏移或水平滚动，请尝试以下步骤：

确保视口元标签正确应用

在 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, 优先使用原生禁用并让 CSS (或 Native Navigation 的) contentInsetMode: 'css') 来控制安全区域：

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重复的安全区域填充或固定宽度容器，而不是视口元标签本身。

结论

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

您实现了以下内容：

配置 Nuxt 以进行静态生成
添加 Capacitor 8 以及必需的插件
在 iOS 和 Android 模拟器上构建和部署
为开发启用实时重载
修复常见的 iOS 布局问题（视口、安全区域、溢出）
添加原生感知的UI体验，使用Capgo原生导航和过渡

下一步:

设置 Capgo 为无线更新而设置
添加更多本机插件，如摄像头、地理位置或推送通知
配置应用程序图标和启动屏幕
为App Store和Google Play准备应用程序

开始一个全新的项目？查看从零开始构建Nuxt移动应用

获取资源

Nuxt 文档
Capacitor 8 文档
@capgo/capacitor-原生导航 —— Liquid Glass tab bar 和原生 chrome
@capgo/capacitor-过渡 —— 原生感知的页面过渡
@capgo/Tailwind-capacitor — Tailwind safe-area utilities for Capacitor
Capgo - Capacitor 应用程序的实时更新

了解如何使用 Capgo 快速构建更好的应用程序注册免费账户今天就开始吧

继续使用 Capacitor 构建 iOS & Android 应用

如果您正在使用 使用 Capacitor 构建 iOS & Android 应用 为原生插件工作做好准备，连接它到 Capgo 插件目录在 Capgo 插件目录中了解产品工作流程在 Capacitor 插件目录中了解 Capgo 的插件在 Capacitor 插件目录中了解 Capgo 的插件实现细节添加或更新插件在添加或更新插件中了解实现细节 Ionic 企业插件替代品在 Ionic 企业插件替代品中了解产品工作流程 Capgo 原生构建为Capgo原生构建的产品工作流程。

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

介绍

使用Nuxt和Capacitor的好处

先决条件

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

添加 Capacitor 8 到您的项目

构建和部署本机应用

Capacitor 实时重载

使用Capacitor插件

原生式 UI 与 Capgo 原生导航和过渡

安全区域与Tailwind

如果内容在 iOS 上被裁剪、偏移或水平滚动，请尝试以下步骤：

确保视口元标签正确应用

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

在Capacitor iOS `contentInset` 到 `never` 首先

找到真正溢出的元素

结论

获取资源

继续使用 Capacitor 构建 iOS & Android 应用

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

介绍

使用Nuxt和Capacitor的好处

先决条件

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

添加 Capacitor 8 到您的项目

构建和部署本机应用

Capacitor 实时重载

使用Capacitor插件

原生式 UI 与 Capgo 原生导航和过渡

安全区域与Tailwind

如果内容在 iOS 上被裁剪、偏移或水平滚动，请尝试以下步骤：

确保视口元标签正确应用

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

在Capacitor iOS contentInset 到 never 首先

找到真正溢出的元素

结论

获取资源

继续使用 Capacitor 构建 iOS &amp; Android 应用

在Capacitor iOS `contentInset` 到 `never` 首先

继续使用 Capacitor 构建 iOS & Android 应用