Capacitor 8

介绍

您已经有一个 Nuxt 网络应用程序吗？本指南将教您如何将其转换为使用 __CAPGO_KEEP_0__ Capacitor __CAPGO_KEEP_0__ 将您的网络应用程序包装在一个本机容器中，使您能够访问设备 API，如摄像头、文件系统和推送通知，而您的现有 Vue 代码库保持不变。与 Flutter 或 React Native 不同，您不需要重写任何内容 ——您的 Nuxt __CAPGO_KEEP_1__ 将保持不变。

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 应用程序以进行静态生成

添加 __CAPGO_KEEP_0__ 8 以便本机插件
Add Capacitor 8 with essential native plugins
启用快速开发的实时重载
__CAPGO_KEEP_0__
解决常见的iOS布局问题（视口、安全区域、水平溢出）
添加本机感知的UI使用Capgo Native导航和过渡

想从头开始一个新项目？检查我们的关于从头开始构建Nuxt移动应用.

使用Nuxt和Capacitor的好处

Code可重用性: 在web和移动应用之间共享Vue组件和逻辑。
性能上下文：首页问题/解决方案部分。角色：部分或页面标题。见于：页面premium-support.astro。消息键`ps_help_performance_title`（Ps Help Performance Title）。
: Nuxt的静态生成创建了优化的包，适合移动设备。: Access device features like camera, geolocation, and filesystem through Capacitor plugins.
: 通过__CAPGO_KEEP_0__插件访问设备功能，如摄像头、地理位置和文件系统。: 使用熟悉的 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/splash-screen:管理原生启动屏幕
@capacitor/status-bar:定制设备状态栏
@capacitor/preferences:键值存储（类似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. For iOS, you need a Mac with iOS需要一个带有.

Xcode

bun run mobile

构建和同步项目:

本过程会运行自定义脚本，生成静态Nuxt构建并同步文件到原生平台。

构建和部署原生应用

要构建和部署原生移动应用，请遵循以下步骤： 要开发iOS应用，您需要安装 Xcode ，而要开发Android应用，您需要安装 Android Studio

打开本机项目：

对于 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 实时重载

在开发过程中，您可以利用实时重载功能，立即在移动设备上看到更改。要启用此功能，请遵循以下步骤：

找到您的本地 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 应用程序进行哪些更改，移动应用程序都会自动重新加载以反映这些更改。

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

使用 Capacitor 插件

Capacitor 插件允许您从 Nuxt 应用程序访问原生设备功能。让我们以 Share 插件为例：安装 Share 插件：创建或更新一个页面以使用 Share 插件。在 Nuxt 4 中，页面位于

同步更改与原生项目：

bun add @capacitor/share

__CAPGO_KEEP_0__ 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>

__CAPGO_KEEP_0__

bun run mobile

或者直接同步而不重建:

bunx cap sync

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

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

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

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

的情况下，很少值得。为了在Nuxt + Capacitor应用中实现原生移动感受，使用Capgo插件而不是仅限Web的UI套件，如Konsta UI:

@capgo/capacitor-native-navigation ——原生导航栏，Liquid Glass标签栏在iOS上，Android上的模糊标签栏样式。您的Nuxt路由保持路由状态；插件拥有原生浏览器。
@capgo/capacitor-transitions —— Ionic风格的页面过渡和iOS边缘滑动返回，在WebView层中实现，而不需要采用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',
  },
});

渲染液态玻璃标签栏（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') context

在导航之前进行。不要在本机导航拥有这些表面时重复Web页眉或页脚。使用@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

实用程序和其他__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 或调整视口标签通常无法解决问题。按照以下顺序检查这些问题。

确保视口元标签已正确应用

在 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.

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 布局问题（视口、安全区域、溢出）
添加了原生感觉的 UI 以及 Capgo 原生导航和过渡

下一步：

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

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

资源

Nuxt文档
Capacitor 8文档
capgo/capacitor-native-navigation —— Liquid Glass滑动条和本机浏览器
capgo/capacitor-transitions — 本地化的页面过渡效果
@capgo/tailwind-capacitor — Tailwind safe-area utilities for Capacitor
Capgo - 实时更新 Capacitor 应用

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

继续阅读 Convert Your Nuxt App to iOS & Android with Capacitor 8

如果您正在使用 Convert Your Nuxt App to iOS & Android with Capacitor 8 规划本地插件工作，连接它到 Capgo 插件目录为 Capgo 产品工作流程 Capacitor 由 Capgo 提供 for the implementation detail in Capacitor Plugins by Capgo, 添加或更新插件为添加或更新插件的实现细节 Ionic 企业插件替代品为 Ionic 企业插件替代品的产品工作流程, 和 Capgo 原生构建为 Capgo 原生构建的产品工作流程

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

介绍