Capacitor 跨平台打包实战：从 Web 到原生应用

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

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

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

npm run build 

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

npx cap add android 

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

npx cap add ios 

添加完成后，项目根目录会出现 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 组件中编写代码。这里使用 Vue 3 的 <script setup> 语法结合 Capacitor 的 Camera 插件实现移动端拍照功能。

模板部分

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

功能实现要点

• 相机权限配置：iOS 需要在 Info.plist 中添加 NSCameraUsageDescription（相机使用说明）；Android 则在 AndroidManifest.xml 中添加相机权限声明。
• 照片质量参数：quality 参数范围 0-100，数值越高照片质量越好但文件体积越大。
• 结果类型选项：CameraResultType 提供三种返回格式：Uri（适用于显示）、Base64（适用于上传）、DataUrl（带前缀的 base64 字符串）。

错误处理建议 常见错误包括用户拒绝相机权限、设备不支持相机功能、存储空间不足。可在 catch 块中添加用户提示：

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

重新构建并同步后，运行 APP 点击'拍照'按钮，就能调用设备相机了。

步骤 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 绝对值得一试。