跳过主要内容
Capgo logo
教程

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

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

文章来源

马丁·多纳迪尤

作者

瓦莱里亚

审阅者

乔丹

编辑

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

简介

已有 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.

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

  • 配置您的现有 Nuxt 应用程序进行静态生成
  • Add Capacitor 8 with essential native plugins
  • 在 iOS 和 Android 模拟器上构建和测试
  • 启用快速开发的实时重载
  • 修复常见的 iOS 布局问题（视口、安全区域、水平溢出）
  • Add native-feeling UI with Capgo Native Navigation and Transitions

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

Benefits of Using Nuxt and Capacitor

  • Code Reusability:在web和移动应用之间共享您的Vue组件和逻辑
  • 性能:Nuxt的静态生成创建了优化的包，适合移动设备
  • 原生功能: Access device features like camera, geolocation, and filesystem through Capacitor plugins.
  • 简化开发:使用熟悉的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 应用打包到本机移动容器中，请遵循以下步骤：

  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/splash-screen:管理原生启动屏幕
  • @capacitor/status-bar:定制设备状态栏
  • @capacitor/preferences:键值存储（类似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，您需要一台 Mac 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

For Android: 

bun run mobile:android

或直接使用 Capacitor CLI: 

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

android-studio-run

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

xcode-run

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

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

nuxtjs-mobile-app

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

Capacitor Live Reload

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

  1. 找到您的本地 IP 地址：

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

    ipconfig getifaddr en0

  • 在 Windows 上运行：

    ipconfig

    在输出中查找 IPv4 地址。

  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

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

  1. __CAPGO_KEEP_0__
bun run dev

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

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

使用 Capacitor 插件

Capacitor 插件允许您从 Nuxt 应用程序访问本机设备功能。让我们探索如何使用 Share 插件作为示例： 安装 Share 插件： 创建或更新一个页面来使用 Share 插件。在 Nuxt 4 中，页面位于

  1. 同步更改与本机项目：
bun add @capacitor/share
  1. 或仅同步而不重建： 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

使用 __CAPGO_KEEP_0__ 插件

bunx cap sync
  1. __CAPGO_KEEP_0__ 插件允许您从 Nuxt 应用程序访问本机设备功能。让我们探索如何使用 Share 插件作为示例：

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

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

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

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

For a native mobile feel in a Nuxt + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta 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',
  },
});

渲染液态玻璃标签栏（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 页面在 cap-router-outlet, cap-page，并且 cap-content，并且调用 setDirection('forward') 或 setDirection('back') context

在导航之前进行。不要在本机导航拥有这些表面时重复 Web 头部或底部。 Using @capgo/capacitor-native-navigation 使用@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation 使用@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仅从根包装器中处理iOS安全区域 app.head:

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

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

将所有页面内容包装在

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

中。重复在头部、模态窗口和布局包装器中添加安全区域填充通常会使UI看起来被裁剪或过大。 .app-shell在

With @capgo/tailwind-capacitor,你可以使用类似于 pt-safe pb-safe px-safe on that single shell.

设置CapacitoriOS 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.

In 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布局问题（视口、安全区域、溢出）
  • 添加了native-feeling UI，使用Capgo Native Navigation和Transitions

下一步：

  • 设置 Capgo 为无线更新而无需重新提交应用商店
  • 添加更多native插件，如Camera、Geolocation或Push Notifications
  • 配置应用图标和启动屏幕
  • 为 App Store 和 Google Play 提交做好准备

开始一个全新的项目？请查看 从零开始构建 Nuxt 移动应用 以指导式教程的形式查看。

资源

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

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

如果您正在使用 将您的Nuxt应用转换为iOS &amp; Android的Capacitor 8 规划原生插件工作，连接它到 Capgo插件目录 Capgo插件目录中的产品工作流 Capacitor插件由Capgo提供 为 Capacitor 的实现细节在 Capgo 插件中 添加或更新插件 为 __CAPGO_KEEP_0__ 的实现细节在添加或更新插件中 Ionic 企业插件替代品 为 Ionic 企业插件替代品的产品工作流程, 和 Capgo 原生构建 为 Capgo 原生构建的产品工作流程

Capacitor应用的实时更新

当一个web层bug活跃时，通过Capgo将修复直接推送到用户，而不是等待几天的app store审批。用户在后台接收更新，而native变化仍在正常的审批路径中。

来自Martin的人性化支持

立即开始

最新博客

Capgo gives you the best insights you need to create a truly professional mobile app.

2-Way Communication in Capacitor Apps
移动 2025年4月26日 +1
Capgo 为您提供了创建真正专业的移动应用所需的最佳见解。

2-Way Communication in Capacitor Apps

开发
development 安全 +1
2025年4月13日

避免的5种OTA更新错误

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

开发

移动