无需域名！用 Cordova 把 Vue3 项目打包成原生 App（附详细步骤）

原创已于 2025-09-30 14:47:15 修改 · 625 阅读

CC 4.0 BY-SA版权

文章标签：

于 2025-09-30 14:46:52 首次发布

在前端开发中，我们经常会遇到 “将 Web 项目转化为原生 App” 的需求。如果直接学习原生开发（Android 的 Kotlin/Java、iOS 的 Swift），成本高且周期长。而 Cordova 作为一款成熟的混合开发工具，能让我们用 Vue3 写的 Web 项目直接打包成可安装的原生 App，关键是全程无需域名，本地就能完成所有操作。

本文就带大家一步步实现：从 Vue3 项目构建，到 Cordova 环境配置，再到最终打包出 Android APK 文件，每一步都附具体操作和避坑指南，新手也能跟着做！

一、前置知识：Cordova 是什么？

在开始前先简单科普下：Cordova（曾用名 PhoneGap）是 Apache 旗下的混合开发框架，它的核心原理是用原生 WebView 承载 Web 页面，同时提供一套原生 API 供 Web 调用（比如相机、通讯录等）。

对于我们 Vue 开发者来说，Cordova 的优势很明显：

零原生开发基础也能上手；
复用现有 Vue 项目代码，无需重写；
本地打包，无需域名和服务器；
最终产物是标准的原生 App 安装包（APK/IPA）。

本文以 Android 平台为例（iOS 需 macOS 环境，步骤类似），所需工具清单如下：

Node.js（建议 16+，需提前安装 npm）；
Vue3 项目（已开发完成，或用 Vue CLI 新建的 demo 项目）；
Android Studio（用于获取 Android SDK 和模拟器）；
Java JDK（Cordova 依赖 Java 环境）；
Gradle（Android 打包工具，可手动安装或让 Cordova 自动下载）。

二、第一步：构建 Vue3 项目产物

首先要把 Vue3 项目打包成静态的 Web 资源（HTML/CSS/JS），这一步和普通的 Web 项目打包完全一致。

1. 执行打包命令

如

npm run build

2. 找到打包产物

打包完成后，项目根目录会生成一个 dist 文件夹，里面就是我们需要的静态资源（index.html 是入口文件，css、js、img 是对应资源）。

注意：如果打包后打开 index.html 是空白页，需检查 Vue 项目的 publicPath 配置：
- Vue CLI 项目：修改 vue.config.js 中的 publicPath: './'（默认是 '/'，本地打开会路径错误）；
- Vite 项目：修改 vite.config.js 中的 base: './'。

三、第二步：配置 Android 开发环境（核心）

Cordova 打包 Android App 依赖 Android SDK，而 Android Studio 是获取 SDK 最便捷的工具（无需手动找 SDK 版本，还能自动配置部分环境）。

1. 安装 Android Studio

1.1 下载 Android Studio

官网下载地址：https://developer.android.com/studio

（如果官网访问慢，可通过国内镜像下载，比如华为开发者联盟的镜像）

1.2 安装时必选组件

安装过程中，会出现 “选择要安装的组件” 界面，必须勾选以下两项：

Android SDK（Cordova 打包依赖的核心文件）；
Android Virtual Device（可选，用于在电脑上模拟手机运行 App）。

其他选项默认即可，点击下一步直到安装完成（安装时间较长，取决于网络速度）。

1.3 找到 SDK 路径

安装完成后，默认的 SDK 路径如下（需记住这个路径，后面配置环境变量要用）：

Windows：C:\Users\<你的用户名>\AppData\Local\Android\Sdk

（比如你的用户名叫 “张三”，路径就是 C:\Users\张三\AppData\Local\Android\Sdk）

2. 配置 Android 环境变量

环境变量的作用是让 Cordova 能找到 Android SDK 的位置，必须配置正确，否则后续打包会报错。

2.1 打开环境变量配置界面

Windows：右键 “此电脑” → “属性” → “高级系统设置” → “环境变量”；

2.2 添加 ANDROID_HOME 系统变量

在 “系统变量”（Windows）或配置文件（Mac）中添加以下变量：

变量名	变量值（SDK 路径）
ANDROID_HOME	Windows：C:\Users <你的用户名>\AppData\Local\Android\Sdk Mac：/Users/<你的用户名>/Library/Android/sdk

2.3 编辑 Path 变量（Windows

在 “系统变量” 中找到 Path（Windows），或在配置文件中添加（Mac），追加以下 3 个路径：

Windows：

%ANDROID_HOME%\platform-tools

%ANDROID_HOME%\tools

%ANDROID_HOME%\tools\bin

2.4 验证环境变量（可选）

配置完成后，关闭所有终端，重新打开一个新终端，执行以下命令：

echo %ANDROID_HOME%  # Windows

如果能输出你配置的 SDK 路径，说明环境变量配置成功。

四、第三步：配置 Java JDK 环境

Cordova 和 Android 打包都依赖 Java JDK，建议安装 JDK 21 版本（兼容性最好，太高版本可能有兼容问题）。

1. 下载 JDK 21

推荐从 Adoptium 下载（免费开源，无需注册）：https://adoptium.net/zh-CN

选择 “Temurin 21”，根据你的系统（Windows/Mac）选择对应的安装包（64 位）。

2. 安装 JDK

双击安装包，一路默认下一步即可（记住安装路径，比如 Windows 默认是 C:\Program Files\Eclipse Adoptium\jdk-21.0.2.13-hotspot）。

3. 配置 JDK 环境变量

3.1 添加 JAVA_HOME 系统变量

和配置 Android 环境变量类似，在 “系统变量” 中新建：

步骤	操作
新建系统变量	变量名：JAVA_HOME 变量值：JDK 的根目录（比如 C:\Program Files\Eclipse Adoptium\jdk-21.0.2.13-hotspot）

3.2 编辑 Path 变量

在 Path 中追加以下路径：

%JAVA_HOME%\bin  # Windows

3.3 验证 JDK 安装

重新打开终端，执行以下命令：

java -version

如果输出类似 openjdk version "21.0.2" 的信息，说明 JDK 配置成功。

五、第四步：用 Cordova 打包 Vue3 项目

环境配置完成后，就可以通过 Cordova 把 Vue 的 dist 产物打包成 APK 了。

1. 全局安装 Cordova CLI

打开终端，执行以下命令安装 Cordova 命令行工具：

npm install -g cordova

安装完成后，执行 cordova -v 验证，如果输出版本号（比如 12.0.0），说明安装成功。

2. 创建 Cordova 项目

在终端中，cd 到你想存放 Cordova 项目的目录（比如 D:\projects），执行以下命令创建项目：

cordova create MyVueApp org.example.myvueapp MyVueApp

这里的三个参数含义如下，可根据你的需求修改：

参数	含义	示例
MyVueApp	项目文件夹名（任意）	会生成 D:\projects\MyVueApp
org.example.myvueapp	包名（反向域名）	是 App 在手机上的唯一标识，不能重复
MyVueApp	App显示名	手机桌面图标下的文字

3. 进入 Cordova 项目目录

创建完成后，cd 到项目根目录：

cd MyVueApp

4. 添加 Android 平台

执行以下命令，让 Cordova 支持 Android 平台打包：

cordova platform add android

这个命令会自动下载 Android 平台相关的依赖（如果网络慢，可能需要几分钟）。

5. 检查环境是否达标（关键）

在打包前，必须确保所有环境依赖都已满足，执行以下命令检查：

cordova requirements

如果环境都配置正确，会输出全绿的信息：

Java JDK: installed 21.0.2

Android SDK: installed

Android target: android-35 installed

Gradle: installed

常见问题解决：

如果某一项显示 ×（比如 Gradle 未安装）：
- 手动下载 Gradle 8.1.3（推荐版本，兼容性好）：https://gradle.org/releases/
- 解压后配置 GRADLE_HOME 环境变量（类似 JAVA_HOME），并将 %GRADLE_HOME%\bin 加入 Path。
如果 Android target 显示 ×：打开 Android Studio，在 SDK Manager 中安装对应的 Android 版本（比如 android-35）。

6. 把 Vue 产物放入 Cordova 项目

找到之前 Vue3 项目打包生成的 dist 文件夹，将 dist 里面的所有文件（index.html、css、js 等）复制到 Cordova 项目的 www 文件夹中（路径：MyVueApp\www）。

⚠️ 注意：是复制 dist 里面的 “内容”，而不是复制 dist 文件夹本身！如果 www 文件夹中原有文件（比如 index.html、css 文件夹），直接覆盖即可。

7. 打包生成 APK 文件

最后一步！执行以下命令开始打包：

cordova build android

打包过程会比较久（第一次打包会下载 Gradle 依赖，后续会快很多），耐心等待。如果没有报错，会显示 “BUILD SUCCESSFUL”。

8. 找到 APK 文件

打包完成后，APK 文件会生成在以下路径：

MyVueApp\platforms\android\app\build\outputs\apk\debug\app-debug.apk

这个 app-debug.apk 就是可安装的 Android 应用安装包，把它传到手机上，点击安装即可运行（手机需要开启 “未知来源应用安装” 权限）。

六、常见问题与避坑指南

打包时提示 “SDK not found”：检查 ANDROID_HOME 环境变量是否配置正确，路径是否存在。
Vue 页面空白页：确保 Vue 打包时 publicPath/base 配置为 ./，且 dist 内容正确复制到 www 文件夹。
Gradle 下载慢：手动下载 Gradle 并配置环境变量，或在 Cordova 项目的 build.gradle 中修改为国内镜像。
手机安装 APK 提示 “解析包错误”：可能是 APK 与手机系统版本不兼容，可在 Cordova 项目的 config.xml 中修改 minSdkVersion（比如改为 21，支持 Android 5.0+）。

七、总结

通过 Cordova 打包 Vue3 项目成原生 App，整个流程并不复杂，核心是环境配置（Android SDK、JDK、Gradle），只要环境配置正确，后续打包就是一条命令的事。

这种方式的优势在于：无需学习原生开发，复用 Web 代码，本地就能完成所有操作，非常适合快速将 Vue 项目转化为 App 进行演示或小范围使用。

如果需要发布到应用商店（比如 Google Play），还需要对 APK 进行签名（Cordova 也提供了签名命令）。