从零开始：使用 Capacitor 将 Web 导航页打包成 Android APK 完整指南

背景

作为一个程序员，手里有一个自己写的纯前端导航页（http://117.72.72.6:23000/，命名为 YuGeNavi），想要把它变成一个可以在手机上独立安装的 APK 应用。

对比了 PakePlus、Tauri 和 Capacitor 之后，最终选择了 Capacitor。原因很简单：它是目前移动端 WebView 封装方案的事实标准，插件生态成熟，方便以后扩展原生功能（如推送、本地存储等），同时 APK 体积也能控制在极小的范围内（约 8MB）。

这篇文章记录了从环境搭建 → 生成签名 APK → 自定义应用图标的完整过程，以及其中踩过的坑。

一、环境准备

Capacitor 8 对开发环境有明确要求，请先确认版本：

依赖	版本要求	验证命令
Node.js	22+（推荐最新 LTS）	`node --version`
Java JDK	21	`java --version`
Android Studio	最新版	-

我的本地环境：

Node.js: v24.15.0
Java: openjdk 21.0.8 LTS
Android Studio: Narwhal 4 Feature Drop (2025.1.4)

二、初始化 Capacitor 项目

1. 创建项目目录并初始化 npm

mkdir yu-navi-app && cd yu-navi-app
npm init -y

踩坑提示：Windows CMD 下不支持 ls 命令，查看目录请使用 dir。

2. 安装 Capacitor 核心依赖

npm i @capacitor/core
npm i -D @capacitor/cli

3. 创建 Web 资源占位目录

即使我们加载的是远程 URL，Capacitor 的构建流程依然要求存在一个 webDir，并且里面至少有一个 index.html。

mkdir www

在 www 目录下新建 index.html，内容随便填，例如：

<!DOCTYPE html>
<html>
<head><meta charset="utf-8"><title>YuGeNavi</title></head>
<body><p>Loading...</p></body>
</html>

4. 初始化 Capacitor 配置

npx cap init "YuGeNavi" "com.yunavi.app" --web-dir=www

此时项目根目录会生成 capacitor.config.json（如果你有 TypeScript 环境，可能生成 .ts）。

三、配置远程 URL 与明文流量（核心坑点）

这是封装远程网站最关键的步骤。

1. 修改 `capacitor.config.json`

打开 capacitor.config.json，修改为：

{
  "appId": "com.yunavi.app",
  "appName": "YuGeNavi",
  "webDir": "www",
  "server": {
    "url": "http://117.72.62.6:23000/",
    "cleartext": true
  }
}

⚠️ 关键点：你的网站是 HTTP 协议。Android 9+ 默认禁止明文 HTTP 请求。如果不加 "cleartext": true，App 打开后会直接白屏。

2. 添加 Android 平台

npm i @capacitor/android
npx cap add android

执行完成后，项目根目录会多出一个 android/ 文件夹。

3. 修改 `AndroidManifest.xml`

打开 android/app/src/main/AndroidManifest.xml，在 <application> 标签中加入 android:usesCleartextTraffic="true"：

<application
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:supportsRtl="true"
    android:theme="@style/AppTheme"
    android:usesCleartextTraffic="true">

⚠️ 极其容易犯的低级错误：我在这里不小心多写了一个 >，导致 Gradle 报 unexpected token 解析错误。XML 标签的闭合只需要一个 >，请务必检查。

4. 同步配置到原生工程

npx cap sync android

四、构建签名 APK

1. 打开 Android Studio

npx cap open android

初次打开时，Android Studio 会弹窗提示 Trust and Open Project（信任项目），直接点击 Trust Project 即可。这是 AS 的安全机制，因为 Gradle 构建脚本可以执行任意代码。

2. 生成签名 APK

在 Android Studio 顶部菜单栏选择 Build → Generate Signed Bundle / APK。

选择 APK：如果你只是自己用或发给朋友，选 APK；如果要上架 Google Play，才需要选 Android App Bundle。
创建密钥库（Keystore）：
- 选择 Create new...。
- 路径选择项目目录下的 yunavi.jks（例如 D:\music\yu-navi-app\yunavi.jks）。
- 设置并牢记密钥库密码、别名（Alias）和密钥密码。
- 有效期默认 25 年即可。
填写证书信息：随便填一下 First and Last Name、Organization 等即可。
选择构建变体：选择 release，并勾选 V1 和 V2 签名。
点击 Finish。

等待右下角提示 Build completed successfully，点击 locate 定位到 APK 文件： android/app/build/outputs/apk/release/app-release.apk

⚠️ 血泪警告：.jks 文件和密码务必备份！这是 App 的唯一身份证，丢了就永远无法覆盖更新，只能让用户卸载重装。

五、自定义应用图标（完整版）

默认的 Android 机器人图标太丑，我们可以用 AI 生成一个专属图标，然后通过 Android Studio 替换。

1. AI 图标生成提示词（推荐）

极简科技风（指南针 + 字母 Y）：

A modern minimal app icon design for a navigation app named “YuGeNavi”. A stylized letter “Y” formed by a compass arrow pointing northeast. Flat vector style with subtle gradients, deep blue to cyan color palette. Rounded square icon, sleek, clean background, high resolution, UI/UX, Dribbble style, no text, clean edges.

3D 玻璃拟态风：

A highly detailed 3D glassmorphism app icon for a personalized navigation dashboard. A glowing letter “Y” in the center, with subtle network nodes and a location pin integrated. Frosted glass texture, vibrant purple to neon blue gradient. Rounded square shape, dark background with soft glowing edges. App Store icon design, modern, 8k resolution, octane render, no text.

建议 AI 生成时要求无文字（no text），因为 AI 拼写经常出错。推荐生成 1024x1024 分辨率。

2. 在 Android Studio 中替换图标

左侧项目栏，切换为 Android 视图。
展开 app → res。
右键点击 res 文件夹，选择 New → Image Asset。
在弹出的 Asset Studio 窗口中：
- Icon Type：保留 Launcher Icons (Adaptive and Legacy)。
- Name：保持默认 ic_launcher。
- Foreground Layer：点击 Path 右侧的文件夹图标，导入你生成的 AI 图片。
- Trim：建议改成 Yes。
- Resize：重点！ 把滑块拖动缩小到 70% 左右，确保图案完整且留出边距，防止被手机系统裁切。
- Background Layer：根据图片风格选择一个纯色背景。
点击 Next → Finish。底部提示 An icon with the same name already exists and will be overwritten. 是正常的，这正是我们想要的效果。

3. 重新打包

图标替换后，重新执行一次 Build → Generate Signed Bundle / APK，用之前的 .jks 签名打包即可。

六、常见问题排查

❓ 打开 App 白屏 99% 是明文流量被拦截。请检查：

capacitor.config.json 中是否加了 "cleartext": true。
AndroidManifest.xml 中是否加了 android:usesCleartextTraffic="true"。
修改后是否执行了 npx cap sync android 并重新打包。

❓ 按手机返回键直接退出应用 这是正常现象，因为 WebView 没有内部历史栈。如果以后需要优化，可以在 MainActivity.java 中覆盖 onBackPressed 方法。

❓ 点击外链没有跳转到系统浏览器 默认情况下，导航页中的外链会在 WebView 内部打开。如果需要跳转到系统浏览器，需要监听 shouldOverrideUrlLoading 并调用 Intent.ACTION_VIEW。

❓ Asset Studio 中预览图标变形或被裁切 这是由于 Android 自适应图标（Adaptive Icons）机制导致的。请确保在 Foreground Layer 中勾选了 Trim: Yes，并将 Resize 调整到 70% 左右，给系统留出安全边距。

总结

使用 Capacitor 将 Web 页面打包为 Android APK，整体流程并不复杂：初始化项目 → 配置远程 URL 和明文流量 → 添加 Android 平台 → Android Studio 打包签名 → 替换自定义图标。

对于纯前端导航页来说，这是一个兼具开发效率和扩展性的方案。生成的 APK 体积仅约 8MB，启动速度快，且未来可以通过 Capacitor 插件生态轻松接入原生推送、本地存储、深链接等功能。

使用Capacitor将Web导航页打包成APK

从零开始使用 Capacitor 将一个纯前端导航页封装成 Android APK，涵盖环境准备、明文流量配置、签名打包以及自定义应用图标的完整流程与踩坑记录。

从零开始：使用 Capacitor 将 Web 导航页打包成 Android APK 完整指南

背景

一、环境准备

二、初始化 Capacitor 项目

1. 创建项目目录并初始化 npm

2. 安装 Capacitor 核心依赖

3. 创建 Web 资源占位目录

4. 初始化 Capacitor 配置

三、配置远程 URL 与明文流量（核心坑点）

1. 修改 `capacitor.config.json`

2. 添加 Android 平台

3. 修改 `AndroidManifest.xml`

4. 同步配置到原生工程

四、构建签名 APK

1. 打开 Android Studio

2. 生成签名 APK

五、自定义应用图标（完整版）

1. AI 图标生成提示词（推荐）

2. 在 Android Studio 中替换图标

3. 重新打包

六、常见问题排查

总结

从零开始：使用 Capacitor 将 Web 导航页打包成 Android APK 完整指南

背景

一、环境准备

二、初始化 Capacitor 项目

1. 创建项目目录并初始化 npm

2. 安装 Capacitor 核心依赖

3. 创建 Web 资源占位目录

4. 初始化 Capacitor 配置

三、配置远程 URL 与明文流量（核心坑点）

1. 修改 capacitor.config.json

2. 添加 Android 平台

3. 修改 AndroidManifest.xml

4. 同步配置到原生工程

四、构建签名 APK

1. 打开 Android Studio

2. 生成签名 APK

五、自定义应用图标（完整版）

1. AI 图标生成提示词（推荐）

2. 在 Android Studio 中替换图标

3. 重新打包

六、常见问题排查

总结

1. 修改 `capacitor.config.json`

3. 修改 `AndroidManifest.xml`