Capacitor 8

介绍

已有Nuxt Web应用？本指南将教您如何使用__CAPGO_KEEP_0__将其转换为native 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 Native Navigation 和 Transitions

想从头开始一个新项目？请参阅我们的指南 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 text fragment from a longer Capgo UI string (parent key `solutions_cordova_to_capacitor_ai_step2_body`). Page/area: Capgo solutions marketing page. Role: Website copy sentence. Seen in: page solutions/cordova-to-capacitor-ai.astro. Message key `solutions_cordova_to_capacitor_ai_step2_body` (Solutions Cordova To Capacitor Ai Step2 Body).

{
  "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 应用打包到原生移动容器中，请遵循以下步骤：

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

In 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

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

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

bun run dev

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

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

使用Capacitor插件

Capacitor 插件使您能够从 Nuxt 应用程序访问本机设备功能。让我们探索如何使用 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集成起来很hacky，并且当您已经有.

For a native mobile feel in a Nuxt + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

@capgo/capacitor-native-navigation @Capacitor/native-navigation
@capgo/capacitor-transitions @Capacitor/transitions

—Ionic样式页面过渡和iOS WebView层中的边缘滑动返回，未采用Ionic UI。

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

安装两者:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

配置原生导航栏的CSS inset模式，以便Web内容尊严原生导航栏:

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

渲染Liquid Glass标签栏（iOS使用系统渲染；Android使用模糊WebView背景）：

<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') 在导航之前包裹页面。不要在原生导航拥有这些表面时重复网页头部或底部。

查看完整指南：使用 @capgo/capacitor 原生导航和使用 @capgo/capacitor 转场.

安全区域使用 Tailwind

为了在 Tailwind CSS 中使用设备安全区域，请使用 @capgo/tailwind-capacitor (发布于) tailwind-capacitor (在 npm)。它提供 safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

(对于 Nuxt 4 与 Tailwind CSS 4，保持此 CSS 文件引用的导入： app/assets/css/main.css:

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

(使用) nuxt.config.ts.

(，和) pt-safe, pb-safe(而不是手动添加) px-safe (项目正在积极开发中 — 如果您的 Nuxt 设置缺少某些内容，请在 __CAPGO_KEEP_0__ 上打开一个 PR： env(safe-area-inset-*) (修复 iOS 布局问题（视口、安全区域和水平溢出）) open a PR on GitHub.

Fixing iOS Layout Issues (Viewport, Safe Area, and Horizontal Overflow)

If content looks cropped, shifted, or horizontally scrollable on iOS, adding more 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@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ pt-safe pb-safe px-safe ，您可以使用类似于

设置 Capacitor iOS `contentInset` 到 `never` 首先

In 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, run:

[...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移动应用程序为指导游览查看Building a Nuxt Mobile App from Scratch

资源

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

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

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

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

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

介绍

使用 Nuxt 和 Capacitor 的好处

先决条件

配置Nuxt应用

添加 Capacitor 8 到您的项目

原生应用构建和部署

Capacitor Live Reload

使用Capacitor插件

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

安全区域使用 Tailwind

Fixing iOS Layout Issues (Viewport, Safe Area, and Horizontal Overflow)

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

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

设置 Capacitor iOS `contentInset` 到 `never` 首先

找到真正溢出的元素

结论

资源

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

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

介绍

使用 Nuxt 和 Capacitor 的好处

先决条件

配置Nuxt应用

添加 Capacitor 8 到您的项目

原生应用构建和部署

Capacitor Live Reload

使用Capacitor插件

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

安全区域使用 Tailwind

Fixing iOS Layout Issues (Viewport, Safe Area, and Horizontal Overflow)

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

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

设置 Capacitor iOS contentInset 到 never 首先

找到真正溢出的元素

结论

资源

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

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

设置 Capacitor iOS `contentInset` 到 `never` 首先

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