287 lines
6.9 KiB
Markdown
287 lines
6.9 KiB
Markdown
|
# 国语教育平台 - 构建说明
|
|||
|
|
|
|||
|
|
## 🎯 问题解决
|
|||
|
|
|
|||
|
|
### 您遇到的问题
|
|||
|
|
运行 `npm run build:app` 后，项目编译成功，但没有生成可安装的 APK 文件。
|
|||
|
|
|
|||
|
|
### 原因说明
|
|||
|
|
**这是正常的！** uni-app 的 CLI 构建命令只负责编译代码，不会生成最终的安装包。
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
npm run build:app → 只编译代码到 unpackage/dist/build/app-plus
|
|||
|
|
❌ 不会生成 APK/IPA 文件
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## ✅ 解决方案
|
|||
|
|
|
|||
|
|
### 方案一：使用 HBuilderX（最简单，强烈推荐）
|
|||
|
|
|
|||
|
|
#### 步骤：
|
|||
|
|
|
|||
|
|
1. **下载 HBuilderX**
|
|||
|
|
- 访问：https://www.dcloud.io/hbuilderx.html
|
|||
|
|
- 下载"App 开发版"（标准版即可）
|
|||
|
|
- 解压即可使用，无需安装
|
|||
|
|
|
|||
|
|
2. **打开项目**
|
|||
|
|
- 启动 HBuilderX
|
|||
|
|
- 点击"文件" -> "打开目录"
|
|||
|
|
- 选择本项目文件夹（`fronted_uniapp`）
|
|||
|
|
|
|||
|
|
3. **云端打包（推荐）**
|
|||
|
|
```
|
|||
|
|
菜单栏 -> 发行 -> 原生App-云打包
|
|||
|
|
```
|
|||
|
|
- ✅ 选择打包平台：Android
|
|||
|
|
- ✅ 使用公共测试证书（快速测试）
|
|||
|
|
- ✅ 点击"打包"按钮
|
|||
|
|
- ⏳ 等待 3-10 分钟
|
|||
|
|
- 📦 下载生成的 APK 文件
|
|||
|
|
|
|||
|
|
4. **安装测试**
|
|||
|
|
- 将 APK 文件传输到 Android 手机
|
|||
|
|
- 安装并测试
|
|||
|
|
|
|||
|
|
#### 优点：
|
|||
|
|
- ✅ 简单快速，无需配置
|
|||
|
|
- ✅ 支持 Android 和 iOS
|
|||
|
|
- ✅ 云端打包，不占用本地资源
|
|||
|
|
- ✅ 自动处理签名和证书
|
|||
|
|
|
|||
|
|
#### 注意事项：
|
|||
|
|
- 需要 DCloud 账号（免费注册）
|
|||
|
|
- 首次使用需要登录
|
|||
|
|
- 云打包有每日次数限制（免费版）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 方案二：使用离线打包（高级用户）
|
|||
|
|
|
|||
|
|
如果您需要完全控制打包过程，可以使用离线打包。
|
|||
|
|
|
|||
|
|
#### Android 离线打包：
|
|||
|
|
|
|||
|
|
1. **准备环境**
|
|||
|
|
- 安装 Android Studio
|
|||
|
|
- 安装 JDK 8 或更高版本
|
|||
|
|
- 下载 uni-app Android 离线 SDK
|
|||
|
|
|
|||
|
|
2. **下载离线 SDK**
|
|||
|
|
- 访问：https://nativesupport.dcloud.net.cn/AppDocs/download/android
|
|||
|
|
- 下载最新版本的 Android 离线 SDK
|
|||
|
|
|
|||
|
|
3. **编译项目**
|
|||
|
|
```bash
|
|||
|
|
npm run build:app
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
4. **集成到离线 SDK**
|
|||
|
|
- 将 `unpackage/dist/build/app-plus` 目录中的文件
|
|||
|
|
- 复制到离线 SDK 的 `assets/apps/__UNI__71560C7__/www/` 目录
|
|||
|
|
|
|||
|
|
5. **使用 Android Studio 打包**
|
|||
|
|
- 用 Android Studio 打开离线 SDK 项目
|
|||
|
|
- 配置签名证书
|
|||
|
|
- Build -> Generate Signed Bundle / APK
|
|||
|
|
- 选择 APK，完成打包
|
|||
|
|
|
|||
|
|
#### iOS 离线打包：
|
|||
|
|
|
|||
|
|
1. **准备环境**
|
|||
|
|
- Mac 电脑
|
|||
|
|
- Xcode
|
|||
|
|
- Apple 开发者账号
|
|||
|
|
- 下载 uni-app iOS 离线 SDK
|
|||
|
|
|
|||
|
|
2. **下载离线 SDK**
|
|||
|
|
- 访问：https://nativesupport.dcloud.net.cn/AppDocs/download/ios
|
|||
|
|
- 下载最新版本的 iOS 离线 SDK
|
|||
|
|
|
|||
|
|
3. **编译和集成**
|
|||
|
|
- 编译项目：`npm run build:app`
|
|||
|
|
- 将编译产物复制到 iOS SDK 的资源目录
|
|||
|
|
- 使用 Xcode 打开项目
|
|||
|
|
- 配置证书和 Provisioning Profile
|
|||
|
|
- Archive 并导出 IPA
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🚀 快速开始
|
|||
|
|
|
|||
|
|
### 使用辅助脚本（推荐）
|
|||
|
|
|
|||
|
|
我已经为您创建了一个辅助脚本，可以帮助您更好地理解构建过程：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# App 平台构建（会显示详细说明）
|
|||
|
|
npm run build:app-help
|
|||
|
|
|
|||
|
|
# H5 平台构建
|
|||
|
|
npm run build:h5-help
|
|||
|
|
|
|||
|
|
# 微信小程序构建
|
|||
|
|
npm run build:mp-weixin-help
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
这些脚本会：
|
|||
|
|
- ✅ 自动清理旧的构建文件
|
|||
|
|
- ✅ 执行构建
|
|||
|
|
- ✅ 显示构建结果
|
|||
|
|
- ✅ 提供下一步操作指南
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📦 各平台打包说明
|
|||
|
|
|
|||
|
|
### H5 平台（Web）
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 构建
|
|||
|
|
npm run build:h5
|
|||
|
|
|
|||
|
|
# 或使用辅助脚本
|
|||
|
|
npm run build:h5-help
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**构建产物位置**: `unpackage/dist/build/h5`
|
|||
|
|
|
|||
|
|
**部署方式**:
|
|||
|
|
- 将整个 `h5` 目录上传到 Web 服务器
|
|||
|
|
- 可以使用 Nginx、Apache 等服务器
|
|||
|
|
- 支持静态文件托管服务（如 Vercel、Netlify）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 微信小程序
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 构建
|
|||
|
|
npm run build:mp-weixin
|
|||
|
|
|
|||
|
|
# 或使用辅助脚本
|
|||
|
|
npm run build:mp-weixin-help
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**构建产物位置**: `unpackage/dist/build/mp-weixin`
|
|||
|
|
|
|||
|
|
**发布步骤**:
|
|||
|
|
1. 下载并安装微信开发者工具
|
|||
|
|
2. 在微信开发者工具中导入 `mp-weixin` 目录
|
|||
|
|
3. 配置 AppID（在 `manifest.json` 中）
|
|||
|
|
4. 点击"上传"按钮
|
|||
|
|
5. 在微信公众平台提交审核
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### App 平台（Android/iOS）
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 构建
|
|||
|
|
npm run build:app
|
|||
|
|
|
|||
|
|
# 或使用辅助脚本（推荐）
|
|||
|
|
npm run build:app-help
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**构建产物位置**: `unpackage/dist/build/app-plus`
|
|||
|
|
|
|||
|
|
**⚠️ 重要**: 此命令只编译代码，不生成安装包！
|
|||
|
|
|
|||
|
|
**生成安装包的方法**:
|
|||
|
|
1. **HBuilderX 云打包**（推荐） - 见方案一
|
|||
|
|
2. **离线打包**（高级） - 见方案二
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🛠️ 常用命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 开发模式（热重载）
|
|||
|
|
npm run dev:h5 # H5 开发
|
|||
|
|
npm run dev:mp-weixin # 微信小程序开发
|
|||
|
|
npm run dev:app # App 开发
|
|||
|
|
|
|||
|
|
# 生产构建
|
|||
|
|
npm run build:h5 # H5 构建
|
|||
|
|
npm run build:mp-weixin # 微信小程序构建
|
|||
|
|
npm run build:app # App 构建
|
|||
|
|
|
|||
|
|
# 辅助构建（带说明）
|
|||
|
|
npm run build:h5-help # H5 构建 + 说明
|
|||
|
|
npm run build:mp-weixin-help # 微信小程序构建 + 说明
|
|||
|
|
npm run build:app-help # App 构建 + 说明
|
|||
|
|
|
|||
|
|
# 清理构建文件
|
|||
|
|
npm run clean
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📋 项目信息
|
|||
|
|
|
|||
|
|
- **项目名称**: 国语教育平台
|
|||
|
|
- **AppID**: `__UNI__71560C7`
|
|||
|
|
- **版本号**: 1.0.0
|
|||
|
|
- **版本代码**: 100
|
|||
|
|
- **框架**: uni-app (Vue 3)
|
|||
|
|
- **最低 Android 版本**: 5.0 (API 21)
|
|||
|
|
- **目标 Android 版本**: 11 (API 30)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## ❓ 常见问题
|
|||
|
|
|
|||
|
|
### Q1: 为什么 `npm run build:app` 不生成 APK？
|
|||
|
|
**A**: 这是正常的。CLI 命令只编译代码，需要使用 HBuilderX 或离线 SDK 才能生成安装包。
|
|||
|
|
|
|||
|
|
### Q2: 可以不用 HBuilderX 吗？
|
|||
|
|
**A**: 可以，但需要配置完整的原生开发环境（Android Studio/Xcode）和离线 SDK，过程较复杂。
|
|||
|
|
|
|||
|
|
### Q3: 云打包收费吗？
|
|||
|
|
**A**: DCloud 提供免费的云打包服务，但有每日次数限制。付费会员可以获得更多次数。
|
|||
|
|
|
|||
|
|
### Q4: 如何生成正式版 APK？
|
|||
|
|
**A**: 在 HBuilderX 云打包时，需要配置自己的签名证书。可以使用 Android Studio 或 keytool 生成证书。
|
|||
|
|
|
|||
|
|
### Q5: iOS 打包需要什么？
|
|||
|
|
**A**: 需要 Mac 电脑、Xcode、Apple 开发者账号（$99/年）和证书。
|
|||
|
|
|
|||
|
|
### Q6: 可以同时打包 Android 和 iOS 吗？
|
|||
|
|
**A**: 可以，在 HBuilderX 云打包时可以同时选择两个平台。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📚 相关资源
|
|||
|
|
|
|||
|
|
- **uni-app 官方文档**: https://uniapp.dcloud.net.cn/
|
|||
|
|
- **HBuilderX 下载**: https://www.dcloud.io/hbuilderx.html
|
|||
|
|
- **离线打包文档**: https://nativesupport.dcloud.net.cn/
|
|||
|
|
- **DCloud 开发者中心**: https://dev.dcloud.net.cn/
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🎉 推荐流程（最快速）
|
|||
|
|
|
|||
|
|
1. ✅ 下载 HBuilderX（5 分钟）
|
|||
|
|
2. ✅ 打开本项目（1 分钟）
|
|||
|
|
3. ✅ 点击"发行" -> "原生App-云打包"（1 分钟）
|
|||
|
|
4. ✅ 选择 Android + 公共测试证书（1 分钟）
|
|||
|
|
5. ⏳ 等待云端打包（5-10 分钟）
|
|||
|
|
6. 📦 下载 APK 并安装测试
|
|||
|
|
|
|||
|
|
**总耗时**: 约 15-20 分钟即可获得可安装的 APK！
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📞 需要帮助？
|
|||
|
|
|
|||
|
|
如果您在打包过程中遇到问题，可以：
|
|||
|
|
1. 查看 `BUILD_GUIDE.md` 获取更详细的说明
|
|||
|
|
2. 访问 uni-app 官方论坛：https://ask.dcloud.net.cn/
|
|||
|
|
3. 查看 DCloud 官方文档
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**祝您打包顺利！🎊**
|