Capacitor 跨平台应用打包实战指南

平台添加流程

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

npx cap add android

iOS 平台添加命令：

npx cap add ios

配置文件注意事项

常见需要手动修改的配置项：

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

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

Capacitor 需要基于构建后的 Web 资源打包，所以先构建项目，再添加对应平台：

构建 Web 项目 执行框架对应的构建命令生成优化后的静态文件。例如 Vue 项目使用：

npm run build

添加 Android 平台支持 通过 Capacitor 添加 Android 平台，生成 Android Studio 工程文件：

npx cap add android

添加 iOS 平台支持 在 macOS 环境下，使用相同方法添加 iOS 平台支持并生成 Xcode 工程：

npx cap add ios

平台特定注意事项

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

npx cap sync android

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

npx cap sync ios

后续开发步骤

Android 应用调试 使用 Android Studio 打开 android 目录进行调试和构建 APK。可连接真机或使用模拟器测试。

iOS 应用调试 通过 Xcode 打开 ios 目录下的工程文件。需要 Apple 开发者账号进行真机测试或使用模拟器。

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

npx cap sync

确保每次构建后平台项目保持更新。

添加完成后，项目根目录会出现 android 和 ios 两个文件夹，这就是完整的原生工程。

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

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

# 重新构建 Web 项目
npm run build
# 同步到原生工程
npx cap sync

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

# 打开 Android Studio
npx cap open android
# 打开 Xcode
npx cap open ios

在 Android Studio 中点击'运行'按钮，就能在模拟器或真机上看到你的 APP 了；iOS 同理，选择模拟器或连接真机后运行即可。

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

下面演示如何在 Web 项目中调用相机功能，首先安装相机插件：

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

照片质量参数 quality 参数范围 0-100，数值越高照片质量越好但文件体积越大。

结果类型选项 CameraResultType 提供三种返回格式：

• Uri: 返回图片路径（适用于显示）
• Base64: 返回 base64 字符串（适用于上传）
• DataUrl: 带前缀的 base64 字符串

错误处理建议

常见错误类型

• 用户拒绝相机权限
• 设备不支持相机功能
• 存储空间不足

增强错误处理 可在 catch 块中添加用户提示：

catch (error) {
  alert('无法访问相机，请检查权限设置');
  console.error('Camera error:', error);
}

平台兼容性说明

支持的平台

• iOS
• Android
• PWA（渐进式 Web 应用）

注意事项 iOS 可能需要额外配置隐私描述，在 Info.plist 中添加：

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

重新构建并同步后，运行 APP 点击'拍照'按钮，就能调用设备相机了。这里需要注意：iOS 需要在 Xcode 中配置相机权限，在 Info.plist 中添加 NSCameraUsageDescription（相机使用说明）；Android 则在 AndroidManifest.xml 中添加相机权限声明。

步骤 5：生成安装包

调试完成后，就可以生成正式安装包了：

• Android：在 Android Studio 中，通过'Build → Generate Signed Bundle / APK'生成 AAB（Google Play 推荐）或 APK。
• iOS：在 Xcode 中，选择'Product → Archive'，然后通过 App Store Connect 上传到应用商店，或导出 IPA 用于测试。

四、Capacitor vs Cordova：该怎么选？

提到 Web 转原生，很多人会想到 Cordova，这里做个对比，帮你快速决策：

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

五、适用场景与注意事项

适用场景

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

注意事项

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

六、总结

Capacitor 的出现，让'Web 一次开发，全平台部署'从口号变成了现实。它既保留了 Web 开发的高效性，又通过优秀的原生集成能力弥补了 Web 应用的短板。如果你是前端开发者，想拓展自己的技术边界，或者需要快速交付跨平台应用，Capacitor 绝对值得一试。