跳过主要内容
Capgo logo
教程

使用 Vue 和 Capacitor 构建移动应用

了解如何使用 Vue、Capacitor 和可选地增强 Capgo Native Navigation、Transitions 和 iOS 布局最佳实践来创建一个移动应用。

马丁·多纳迪厄

马丁·多纳迪厄

内容营销人员
使用 Vue 和 Capacitor 构建移动应用

在本教程中，我们将指导您将 Vue 网站应用转换为使用 Capacitor 的原生移动应用。您还可以添加 Capgo Native Navigation 和 Transitions 以获得原生移动体验，并使用 tailwind-capacitor 来安全区域。

关于 Capacitor

Capacitor 是一个革命性的工具，它使您能够轻松将其集成到任何 web 项目中，并将应用转换为原生移动应用。它为您生成原生 Xcode 和 Android Studio 项目，并提供通过 JavaScript 桥访问原生设备功能，如相机的访问。

准备您的 Vue 应用

首先，通过运行以下命令创建一个新的 Vue 应用：

vue create my-app
cd my-app
npm install

为了让您的 Vue 应用准备好部署到原生移动设备上，您需要导出您的项目。 在您的 文件中添加一个脚本来构建和复制 Vue 项目： 运行后，您应该在项目根目录看到一个新的 

{
  "scripts": {
    // ...
    "build": "vue-cli-service build"
  }
}

文件夹。这个文件夹将在后面由 build 用于 Vue 应用 dist folder in your project’s root directory. This folder will be used by Capacitor later.

Adding Capacitor to Your Vue App

作为开发依赖项，并在您的项目中设置它。 在设置过程中，接受默认的名称和包 ID 值。

  1. Install the Capacitor CLI as a development dependency and set it up within your project. Accept the default values for name and bundle ID during the setup.

  2. 添加平台，

  3. Add the platforms, and Capacitor will create folders for each platform at the root of your project:

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your Vue project
npx cap init

# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android

# Add the native platforms
npx cap add ios
npx cap add android

您现在应该看到新的 iOS 和 Android 更新

__CAPGO_KEEP_0__.config.json capacitor.config.json 现在，您可以构建您的Vue项目并同步它与__CAPGO_KEEP_0__: 构建和部署原生应用 iOS

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "dist"
}

Now, you can build your Vue project and sync it with Capacitor:

npm run build
npx cap sync

安卓

To develop iOS apps, you need Xcode installed, and for Android apps, you need Android Studio installed. Additionally, you need to enroll in the Apple Developer Program for iOS and the Google Play Console for Android to distribute your app on the app store.

使用 Capacitor CLI 打开两个本机项目:

npx cap open ios
npx cap open android

使用 Android Studio 或 Xcode 将应用程序部署到连接的设备。

Capacitor 实时重载

在移动设备上启用实时重载，通过让 Capacitor 应用程序从您的网络上的特定 URL 加载内容。

找到您的本地 IP 地址并更新文件中的 IP 和端口: capacitor.config.ts 将这些更改复制到您的本机项目中:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:8080',
    cleartext: true
  }
};

export default config;

现在，您的应用程序将自动重载并显示更改，当您更新您的 Vue 应用程序时。

npx cap copy

使用 __CAPGO_KEEP_0__ 插件

安装一个 Capacitor 插件，例如分享插件，并在您的 Vue 应用程序中使用它:

Install a Capacitor plugin, such as the Share plugin, and use it in your Vue app:

npm i @capacitor/share

导入包并调用__CAPGO_KEEP_0__ share() 在您的应用程序中：

<template>
  <div>
    <h1>Welcome to Vue and Capacitor!</h1>
    <button @click="share">Share now!</button>
  </div>
</template>

<script setup lang="ts">
import { Share } from '@capacitor/share';

async function share() {
  await Share.share({
    title: 'Open Youtube',
    text: 'Check new video on youtube',
    url: 'https://www.youtube.com',
    dialogTitle: 'Share with friends'
  });
}
</script>

安装新插件后，运行命令并将应用程序重新部署到您的设备： sync 下一步，您可以使应用程序在 iOS 和 Android 上感觉更原生，使用 __CAPGO_KEEP_0__ 导航和过渡，并修复常见的 iOS 布局问题，例如水平溢出或裁剪安全区域。

npx cap sync

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

Native-feeling UI with Capgo Native Navigation and Transitions

Ionic 来构建跨平台应用程序，但将其与 Vue 集成时会感到hacky，并且当您已经有 Tailwind CSS 在 Vue + __CAPGO_KEEP_0__ 应用程序中实现原生移动感知，使用 __CAPGO_KEEP_1__ 插件代替仅限 web 的 UI 套件，如 Konsta UI：.

@Capacitor/Capgo-native-navigation

安装两者：

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 标签栏（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') context

查看完整指南： 使用@capgo/capacitor-native-navigation 和 使用@capgo/capacitor-transitions.

安全区域

对于Tailwind CSS中的设备安全区域，使用 @capgo/tailwind-capacitor (发布于 tailwind-capacitor @npm safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

实用工具和其他 src/assets/main.css:

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

@__CAPGO_KEEP_0__ pt-safe, pb-safe-友好的Tailwind插件： px-safe 取代手动添加 env(safe-area-inset-*) 为您的 Vue 设置缺少什么， 在 GitHub 上提交 PR.

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

如果 iOS 内容被裁切、偏移或水平滚动， overflow-x: hidden 仅添加或调整视口标签通常无法解决问题。按照以下顺序检查这些问题。

确保视口元标签正确应用

在 index.html 添加视口元标签在 <head>:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

处理 iOS 安全区域从一个根包装器中

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

html,
body,
#app {
  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: 'dist',
  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, 重复的安全区域填充，或一个固定宽度的容器 —— 不是来自视口元标签本身。

结论

Capacitor 是基于现有 web 项目构建原生应用的很好选择。通过添加 Capgo，甚至更容易为您的应用添加实时更新，使您的用户始终可以访问最新的功能和 bug 修复。

了解如何 Capgo 帮助您快速构建更好的应用 注册免费账户 今天

继续使用 Vue 和 Capacitor 构建移动应用

如果您正在使用 使用 Vue 和 Capacitor 构建移动应用 规划原生媒体和界面行为，连接它与 使用 @capgo/capacitor-live-activities 原生能力在使用 @capgo/capacitor-live-activities 中 @capgo/capacitor-live-activities 原生能力在 @capgo/capacitor-live-activities 中 使用 @capgo/capacitor-video-player 为使用 @capgo/capacitor-video-player 的原生能力 @capgo/capacitor-video-player 为 @capgo/capacitor-video-player 的实现细节 使用 @capgo/capacitor-native-navigation 为使用 @capgo/capacitor-native-navigation 的原生能力

Capacitor 应用实时更新

当 web 层 bug 活跃时，通过 Capgo 将修复推送，而不是等待几天的应用商店审批。用户在后台接收更新，而原生变化保持在正常审批路径中。

来自 Martin 的人性化支持

立即开始

最新博客文章

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

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

Capacitor

5种OTA更新错误的常见问题
5种OTA更新错误的常见问题 开发 +1
安全

2025年4月13日

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

5 移动应用安全最佳实践

查看所有博客文章