跳过主要内容
Capgo logo
教程

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

将您的现有Nuxt 4 Web应用转换为原生iOS和Android移动应用使用Capacitor 8。配置静态生成、添加原生插件并部署到应用商店的完整指南。

马丁·多纳迪厄

马丁·多纳迪厄

内容营销
使用Capacitor 8将您的Nuxt应用转换为iOS & Android

介绍

您是否有现有的Nuxt Web应用？本指南将教您如何使用__CAPGO_KEEP_0__将其转换为原生iOS和Android移动应用 Capacitor 8 — 最新版本，性能和新功能都有所改进

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

What you’ll learn:

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

想从头开始一个新项目？请查看我们的指南 Building a Nuxt Mobile App from Scratch.

使用 Nuxt 和 Capacitor 的好处

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

先决条件

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

  • Node.js 18+ 已安装
  • 一个现有的 Nuxt 4 移动应用
  • Xcode (仅限 macOS)
  • Android 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"
  }
}

包含生成脚本： If you’re using server-side features (API routes, server middleware, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

测试静态生成：

bun run generate

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

在您的项目中添加 Capacitor 8

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

  1. 安装 Capacitor 核心和 CLI：
bun add @capacitor/core
bun add -D @capacitor/cli
  1. 安装常见的 Capacitor 插件：您可能需要的
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

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

  • @capacitor/app: 处理应用程序生命周期事件（前台/后台、深度链接）
  • @capacitor/keyboard: 在移动设备上控制键盘行为
  • @capacitor/启动屏幕:管理原生启动屏幕
  • @capacitor/状态栏:定制设备状态栏
  • @capacitor/偏好设置:原生键值存储（类似localStorage）
  1. 初始化Capacitor项目详细信息：
bunx cap init my-app com.example.myapp --web-dir .output/public

替换 my-app 为您的应用程序名称 com.example.myapp 为您的应用程序ID（逆域名表示法）

  1. 创建或更新 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;
  1. 安装本机平台：
bun add @capacitor/ios @capacitor/android
  1. 添加本机平台文件夹：
bunx cap add ios
bunx cap add android

Capacitor 将创建 ios 并 android 项目根目录下包含本机项目的文件夹。

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

  1. 构建和同步您的项目：
bun run mobile

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

构建和部署本机应用

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

为了开发iOS应用，您需要安装 Xcode ，并且对于Android应用，您需要安装 Android Studio 。此外，如果您计划将应用发布到应用商店，则需要为iOS注册Apple Developer Program，并为Android注册Google Play Console。

  1. 打开原生项目：

对于iOS：

bun run mobile:ios

对于Android：

bun run mobile:android

或直接使用Capacitor CLI：

bunx cap open ios
bunx cap open android
  1. 构建并运行应用：

android-studio-run

  • In Android Studio, wait for the project to be ready, and then click on the “Run” button to deploy the app to a connected device or emulator.

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

  • In Xcode, set up your signing account to deploy the app to a real device. If you haven’t done this before, Xcode will guide you through the process (note that you need to be enrolled in the Apple Developer Program). Once set up, click on the “Play” button to run the app on your connected device.

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

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

nuxtjs-移动应用

Capacitor Live Reload

__CAPGO_KEEP_0__ 实时重载

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

  • 找到您的本地 IP 地址：

    ipconfig getifaddr en0

  • 在 macOS 上，在终端中运行以下命令：

    ipconfig

    在 Windows 上运行：

  1. 更新您的 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).

  1. 将更改应用到您的本机项目:
bunx cap copy

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

  1. 启动您的 Nuxt 开发服务器并在 Xcode/Android Studio 中重建:
bun run dev

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

注意: 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.

Using Capacitor Plugins

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

  1. 安装 Share 插件：
bun add @capacitor/share
  1. 创建或更新一个页面来使用 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>
  1. 同步更改与本机项目：
bun run mobile

或仅同步而不重建：

bunx cap sync
  1. 重建并在设备上运行应用程序。

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

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

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

我已经为 ionic 构建跨平台应用程序，但将其与 Nuxt 集成起来很hacky，并且当您已经有 Tailwind CSS.

在 Nuxt + Capacitor 应用程序中获得原生移动体验，使用 Capgo 插件代替仅限 web 的 UI 套件，如 Konsta UI:

  • @capgo/capacitor-native-navigation — 原生导航栏、Liquid Glass iOS tab栏和 Android 模糊 tab栏样式。您的 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>

Wrap routed pages in 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 utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

工具和其他 __CAPGO_KEEP_0__ 友好的 Tailwind 插件: app/assets/css/main.css:

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

在 nuxt.config.ts.

对于使用 Nuxt 4 和 Tailwind CSS 4 的项目，请在 CSS 文件中保留以下导入语句: pt-safe, pb-safe使用工具类 px-safe , env(safe-area-inset-*) 而不是手动添加 通过手动添加这些工具类来修复问题。该项目正在积极开发中，如果您的 Nuxt 设置缺少某些功能，请在 GitHub 上提交 PR.

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

如果内容在 iOS 上被裁剪、偏移或水平滚动，请添加更多 overflow-x: hidden 或仅仅是调整 viewport 标签通常无法解决问题。按照以下顺序逐一检查。

确保 viewport 元信息标签正确应用

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

设置 Capacitor iOS contentInset 到 never 首先

在 capacitor.config.ts，优先使用原生 inset 并让 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 网站应用转换为使用 Capacitor 8 的原生 iOS 和 Android 应用。您的 Vue 代码库现在可以在移动设备上原生运行，访问设备 API。

您完成了什么：

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

下一步：

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

开始一个全新的项目？请查看 从零开始构建 Nuxt 移动应用 获取一步一步的指引。

资源

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

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

如果您正在使用 将您的 Nuxt 应用程序转换为 iOS &amp; Android 使用 Capacitor 8 为了计划原生插件工作，连接它与 Capgo 插件目录 为产品工作流程在 Capgo 插件目录中 Capacitor 由 Capgo 提供的插件 为 Capacitor 由 Capgo 提供的插件的实现细节 添加或更新插件 添加或更新插件的实现细节 Ionic 企业插件替代方案 为 Ionic Enterprise Plugin Alternatives 中的产品工作流程 Capgo 原生构建 为产品工作流程在Capgo原生构建中。

Capacitor 应用的实时更新

当一个 web-layer 错误活跃时，通过 Capgo 将修复推送到应用程序，而不是等待几天的应用商店审批。用户在后台接收更新，而本机更改保持在正常审批路径中。

来自马丁的人性化支持

立即开始

最新博客文章

Capgo 为您提供了创建真正专业的移动应用所需的最佳见解。

Capacitor 应用的双向通信
开发 移动 +1
2025年4月26日

双向通信在Capacitor应用中

避免的5种OTA更新常见错误
开发 安全性 +1
页面/区域:企业产品/定价页面。角色: UI标签。见于:企业.astro页面。消息键`enterprise_hero_security_label`(企业英雄安全标签)。

2025年4月13日

移动应用实时更新的5种安全最佳实践
移动应用实时更新的5种安全最佳实践 开发 +1
2025年1月14日

移动应用程序实时更新的5条安全最佳实践

查看我们博客的所有内容