Capacitor 跨平台打包实战：Web 应用转原生 App

平台添加流程

初始化后需添加目标平台（以 Android 为例）：

npx cap add android 

iOS 平台添加命令：

npx cap add ios 

配置文件注意事项：

• webDir：默认指向 dist 目录，应匹配实际构建输出目录
• plugins：需要在此处声明使用的 Capacitor 插件
• server：开发服务器配置项

步骤 2：构建 Web 项目并添加平台

Capacitor 需要基于构建后的 Web 资源打包。

构建 Web 项目

npm run build 

添加 Android 平台支持

npx cap add android 

添加 iOS 平台支持

npx cap add ios 

平台特定注意事项

Android 开发环境要求：确保已安装 Android Studio 和 JDK。构建后的 Web 资源需要同步到 Android 项目：

npx cap sync android 

iOS 开发环境要求：需要 Xcode 和 macOS 系统。同步 Web 资源到 iOS 项目：

npx cap sync ios 

持续集成建议：在 CI/CD 管道中添加平台同步命令：

npx cap sync 

步骤 3：同步代码与运行调试

修改 Web 代码后，重新构建并同步到原生工程：

npm run build
npx cap sync

然后打开原生 IDE 进行调试：

npx cap open android
npx cap open ios

步骤 4：调用原生 API（以相机为例）

首先安装相机插件：

npm install @capacitor/camera
npx cap sync

然后在 Vue 组件中编写代码：

<template>
  <div>
    <button @click="takePhoto">拍照</button>
    <img v-if="imageUrl" :src="imageUrl" alt="拍摄的照片">
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { Camera, CameraResultType } from '@capacitor/camera';

const imageUrl = ref('');

const takePhoto = async () => {
  try {
    const image = await Camera.getPhoto({
      quality: 90,
      allowEditing: true,
      resultType: CameraResultType.Uri
    });
    imageUrl.value = image.webPath;
  } catch (error) {
    console.log('拍照失败：', error);
  }
};
</script>

相机权限配置

在 capacitor.config.ts 中需要添加相机权限：

{ "plugins": { "Camera": { "useLimitedLibrary": false } } }

结果类型选项

• Uri: 返回图片路径
• Base64: 返回 base64 字符串
• DataUrl: 带前缀的 base64 字符串

平台兼容性说明 iOS 需要在 Xcode 中配置相机权限，在 Info.plist 中添加：

<key>NSCameraUsageDescription</key>
<string>需要相机权限来拍摄照片</string>

Android 则在 AndroidManifest.xml 中添加相机权限声明。

步骤 5：生成安装包

• Android：在 Android Studio 中，通过'Build → Generate Signed Bundle / APK'生成 AAB 或 APK。
• iOS：在 Xcode 中，选择'Product → Archive'，导出 IPA 用于测试或上传至应用商店。

四、Capacitor vs Cordova：该怎么选？

结论：如果是新项目，优先选 Capacitor；如果是旧的 Cordova 项目，也可以通过 Capacitor 兼容迁移。

五、适用场景与注意事项

适用场景

• Web 开发者快速构建跨平台应用
• 已有 Web 项目低成本扩展为移动应用
• 小团队或创业项目，缺乏原生开发资源
• 需要平衡开发效率与应用性能的场景

注意事项

• 高性能游戏或复杂动画场景，建议用原生或 Flutter，WebView 仍有性能瓶颈
• 不同平台的 WebView 存在细微差异，需做兼容性测试
• 原生权限配置是必做步骤，否则 API 无法正常调用
• 发布应用商店时，需遵循各平台的规范（如图标尺寸、隐私政策等）

六、总结

Capacitor 的出现，让'Web 一次开发，全平台部署'成为现实。它既保留了 Web 开发的高效性，又通过优秀的原生集成能力弥补了 Web 应用的短板。适合前端开发者拓展技术边界，或需要快速交付跨平台应用的场景。