初始化
This commit is contained in:
396
启动文档.md
Normal file
396
启动文档.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# 小程序启动文档
|
||||
|
||||
本文档介绍如何启动小程序的 H5 版本、微信小程序版本，以及通过 HBuilderX 启动小程序。
|
||||
|
||||
---
|
||||
|
||||
## 📋 前置要求
|
||||
|
||||
### 环境要求
|
||||
|
||||
- **Node.js**: >= 20
|
||||
- **pnpm**: >= 9（必须使用 pnpm，项目已配置强制使用）
|
||||
- **微信开发者工具**（用于调试小程序）
|
||||
- **HBuilderX**（可选，用于通过 HBuilderX 启动）
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
# 进入项目目录
|
||||
cd yudao-ui-admin-uniapp
|
||||
|
||||
# 安装依赖（使用 pnpm）
|
||||
pnpm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 方式一：启动 H5 版本
|
||||
|
||||
### 1. 开发环境启动
|
||||
|
||||
```bash
|
||||
# 启动 H5 开发服务器（默认端口：5173）
|
||||
pnpm dev:h5
|
||||
|
||||
# 或者直接使用（会默认启动 H5）
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
启动成功后，浏览器会自动打开 `http://localhost:5173`，或者在控制台查看具体的访问地址。
|
||||
|
||||
### 2. 测试环境启动
|
||||
|
||||
```bash
|
||||
pnpm dev:h5:test
|
||||
```
|
||||
|
||||
### 3. 生产环境启动
|
||||
|
||||
```bash
|
||||
pnpm dev:h5:prod
|
||||
```
|
||||
|
||||
### 4. 构建 H5 版本
|
||||
|
||||
```bash
|
||||
# 开发环境构建
|
||||
pnpm build:h5
|
||||
|
||||
# 测试环境构建
|
||||
pnpm build:h5:test
|
||||
|
||||
# 生产环境构建
|
||||
pnpm build:h5:prod
|
||||
```
|
||||
|
||||
构建完成后，文件会输出到 `dist/dev/h5` 或 `dist/build/h5` 目录。
|
||||
|
||||
---
|
||||
|
||||
## 📱 方式二：启动微信小程序（命令行方式）
|
||||
|
||||
### 1. 开发环境启动
|
||||
|
||||
```bash
|
||||
# 启动微信小程序开发
|
||||
pnpm dev:mp-weixin
|
||||
|
||||
# 或者使用简写
|
||||
pnpm dev:mp
|
||||
```
|
||||
|
||||
执行命令后：
|
||||
1. 项目会自动编译到 `dist/dev/mp-weixin` 目录
|
||||
2. 自动打开微信开发者工具（如果已安装）
|
||||
3. 在微信开发者工具中导入项目目录：`dist/dev/mp-weixin`
|
||||
|
||||
### 2. 测试环境启动
|
||||
|
||||
```bash
|
||||
pnpm dev:mp-weixin:test
|
||||
# 或
|
||||
pnpm dev:mp:test
|
||||
```
|
||||
|
||||
### 3. 生产环境启动
|
||||
|
||||
```bash
|
||||
pnpm dev:mp-weixin:prod
|
||||
# 或
|
||||
pnpm dev:mp:prod
|
||||
```
|
||||
|
||||
### 4. 构建微信小程序
|
||||
|
||||
```bash
|
||||
# 开发环境构建
|
||||
pnpm build:mp-weixin
|
||||
# 或
|
||||
pnpm build:mp
|
||||
|
||||
# 测试环境构建
|
||||
pnpm build:mp:test
|
||||
|
||||
# 生产环境构建
|
||||
pnpm build:mp:prod
|
||||
```
|
||||
|
||||
构建完成后，文件会输出到 `dist/dev/mp-weixin` 或 `dist/build/mp-weixin` 目录。
|
||||
|
||||
### 5. 在微信开发者工具中打开
|
||||
|
||||
1. 打开微信开发者工具
|
||||
2. 选择"导入项目"
|
||||
3. 选择项目目录：`yudao-ui-admin-uniapp/dist/dev/mp-weixin`
|
||||
4. 填写 AppID（如果是测试号，可以使用测试号 AppID）
|
||||
5. 点击"导入"
|
||||
|
||||
**注意事项：**
|
||||
- 如果微信开发者工具没有自动打开，需要手动打开并导入编译后的目录
|
||||
- 确保在微信开发者工具中设置了正确的 AppID
|
||||
- 如果是测试，可以使用测试号
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 方式三：通过 HBuilderX 启动小程序
|
||||
|
||||
### 前置准备
|
||||
|
||||
1. **下载并安装 HBuilderX**
|
||||
- 下载地址：https://www.dcloud.io/hbuilderx.html
|
||||
- 推荐使用 HBuilderX 正式版
|
||||
|
||||
2. **配置 HBuilderX**
|
||||
- 安装微信小程序开发插件（通常已内置）
|
||||
- 配置微信开发者工具路径（设置 -> 插件配置 -> 微信小程序）
|
||||
|
||||
### 方法一：直接打开项目（推荐使用命令行方式）
|
||||
|
||||
**注意**：本项目基于 **unibest** 框架，使用 **Vite** 构建，**不需要依赖 HBuilderX**。建议使用命令行方式启动（方式二）。
|
||||
|
||||
如果你一定要使用 HBuilderX：
|
||||
|
||||
1. 打开 HBuilderX
|
||||
2. 点击"文件" -> "打开目录"
|
||||
3. 选择项目目录：`yudao-ui-admin-uniapp`
|
||||
4. 在项目根目录，点击"运行" -> "运行到小程序模拟器" -> "微信开发者工具"
|
||||
|
||||
**⚠️ 重要提示：**
|
||||
- 本项目使用 Vite 构建，HBuilderX 可能无法正确识别项目结构
|
||||
- 建议使用命令行方式（`pnpm dev:mp-weixin`）编译后，再用 HBuilderX 打开编译后的目录
|
||||
|
||||
### 方法二：打开编译后的目录（推荐）
|
||||
|
||||
1. **使用命令行编译项目**
|
||||
```bash
|
||||
# 在项目根目录执行
|
||||
pnpm dev:mp-weixin
|
||||
```
|
||||
|
||||
2. **在 HBuilderX 中打开编译后的目录**
|
||||
- 打开 HBuilderX
|
||||
- 点击"文件" -> "打开目录"
|
||||
- 选择目录：`yudao-ui-admin-uniapp/dist/dev/mp-weixin`
|
||||
- 在 HBuilderX 中点击"运行" -> "运行到小程序模拟器" -> "微信开发者工具"
|
||||
|
||||
---
|
||||
|
||||
## 🔧 环境配置
|
||||
|
||||
### 环境变量文件
|
||||
|
||||
项目使用环境变量文件进行配置，配置文件位于 `env/` 目录：
|
||||
|
||||
- `.env` - 默认配置
|
||||
- `.env.development` - 开发环境配置
|
||||
- `.env.test` - 测试环境配置
|
||||
- `.env.production` - 生产环境配置
|
||||
|
||||
### 常用配置项
|
||||
|
||||
```env
|
||||
# 服务端地址
|
||||
VITE_SERVER_BASEURL=http://1.14.158.154:48080
|
||||
|
||||
# 应用标题
|
||||
VITE_APP_TITLE=芋道管理后台
|
||||
|
||||
# H5 端口
|
||||
VITE_APP_PORT=5173
|
||||
|
||||
# 租户开关
|
||||
VITE_APP_TENANT_ENABLE=true
|
||||
|
||||
# 验证码开关
|
||||
VITE_APP_CAPTCHA_ENABLE=true
|
||||
|
||||
# 微信小程序 AppID
|
||||
VITE_WX_APPID=your-appid
|
||||
```
|
||||
|
||||
**配置说明：**
|
||||
- 根据实际后端地址修改 `VITE_SERVER_BASEURL`
|
||||
- 微信小程序需要配置正确的 AppID
|
||||
- 租户功能在小程序中已默认设置为租户ID 129
|
||||
|
||||
---
|
||||
|
||||
## 📝 常用命令汇总
|
||||
|
||||
### 开发命令
|
||||
|
||||
```bash
|
||||
# H5 开发
|
||||
pnpm dev:h5 # 开发环境
|
||||
pnpm dev:h5:test # 测试环境
|
||||
pnpm dev:h5:prod # 生产环境
|
||||
|
||||
# 微信小程序开发
|
||||
pnpm dev:mp-weixin # 开发环境（推荐）
|
||||
pnpm dev:mp # 简写（等同于 dev:mp-weixin）
|
||||
pnpm dev:mp:test # 测试环境
|
||||
pnpm dev:mp:prod # 生产环境
|
||||
|
||||
# 其他小程序平台
|
||||
pnpm dev:mp-alipay # 支付宝小程序
|
||||
pnpm dev:mp-baidu # 百度小程序
|
||||
pnpm dev:mp-qq # QQ 小程序
|
||||
pnpm dev:mp-toutiao # 字节跳动小程序
|
||||
```
|
||||
|
||||
### 构建命令
|
||||
|
||||
```bash
|
||||
# H5 构建
|
||||
pnpm build:h5 # 开发环境构建
|
||||
pnpm build:h5:test # 测试环境构建
|
||||
pnpm build:h5:prod # 生产环境构建
|
||||
|
||||
# 微信小程序构建
|
||||
pnpm build:mp-weixin # 开发环境构建
|
||||
pnpm build:mp # 简写
|
||||
pnpm build:mp:test # 测试环境构建
|
||||
pnpm build:mp:prod # 生产环境构建
|
||||
```
|
||||
|
||||
### 其他命令
|
||||
|
||||
```bash
|
||||
# 代码检查
|
||||
pnpm lint # ESLint 检查
|
||||
pnpm lint:fix # ESLint 自动修复
|
||||
|
||||
# TypeScript 类型检查
|
||||
pnpm type-check
|
||||
|
||||
# 初始化项目文件
|
||||
pnpm init-baseFiles
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 常见问题
|
||||
|
||||
### 1. 提示找不到 pnpm
|
||||
|
||||
**解决方案：**
|
||||
```bash
|
||||
# 安装 pnpm
|
||||
npm install -g pnpm
|
||||
|
||||
# 验证安装
|
||||
pnpm -v
|
||||
```
|
||||
|
||||
### 2. 微信开发者工具没有自动打开
|
||||
|
||||
**解决方案：**
|
||||
- 手动打开微信开发者工具
|
||||
- 选择"导入项目"
|
||||
- 选择目录：`dist/dev/mp-weixin`
|
||||
- 填写 AppID 并导入
|
||||
|
||||
### 3. 端口被占用
|
||||
|
||||
**解决方案：**
|
||||
- 修改 `env/.env.development` 中的 `VITE_APP_PORT` 配置
|
||||
- 或者关闭占用端口的其他程序
|
||||
|
||||
### 4. 编译失败
|
||||
|
||||
**解决方案：**
|
||||
```bash
|
||||
# 清理 node_modules 和缓存
|
||||
rm -rf node_modules
|
||||
rm -rf dist
|
||||
rm -rf .vite
|
||||
|
||||
# 重新安装依赖
|
||||
pnpm install
|
||||
|
||||
# 重新编译
|
||||
pnpm dev:mp-weixin
|
||||
```
|
||||
|
||||
### 5. HBuilderX 无法识别项目
|
||||
|
||||
**解决方案：**
|
||||
- 本项目基于 Vite + uni-app，不依赖 HBuilderX 的编译
|
||||
- 建议使用命令行方式编译：`pnpm dev:mp-weixin`
|
||||
- 然后在 HBuilderX 中打开编译后的目录：`dist/dev/mp-weixin`
|
||||
|
||||
### 6. 小程序中租户相关问题
|
||||
|
||||
**说明：**
|
||||
- 小程序已默认设置租户ID为 129
|
||||
- 无需手动选择租户
|
||||
- 相关代码已自动处理
|
||||
|
||||
---
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- **unibest 官方文档**：https://unibest.tech
|
||||
- **uni-app 官方文档**：https://uniapp.dcloud.io
|
||||
- **wot-design-uni 组件库**：https://wot-design-uni.pages.dev
|
||||
- **芋道框架文档**：https://doc.iocoder.cn
|
||||
|
||||
---
|
||||
|
||||
## 💡 开发建议
|
||||
|
||||
1. **推荐使用命令行方式启动**
|
||||
- 项目基于 Vite 构建，命令行方式更高效
|
||||
- 支持热更新，开发体验更好
|
||||
|
||||
2. **使用 VS Code 开发**
|
||||
- 推荐安装 Vue、TypeScript、UnoCSS 等插件
|
||||
- 支持代码提示和自动补全
|
||||
|
||||
3. **调试建议**
|
||||
- H5：直接在浏览器中调试，可使用 Chrome DevTools
|
||||
- 小程序：使用微信开发者工具进行调试
|
||||
- 可以使用 `console.log` 进行调试（生产环境会自动移除）
|
||||
|
||||
4. **代码规范**
|
||||
- 项目已配置 ESLint 和 Prettier
|
||||
- 提交前会自动检查代码规范
|
||||
- 建议使用 `pnpm lint:fix` 自动修复代码格式问题
|
||||
|
||||
---
|
||||
|
||||
## 🎯 快速开始
|
||||
|
||||
### 第一次启动
|
||||
|
||||
```bash
|
||||
# 1. 进入项目目录
|
||||
cd yudao-ui-admin-uniapp
|
||||
|
||||
# 2. 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 3. 配置环境变量（编辑 env/.env.development）
|
||||
# 设置后端地址：VITE_SERVER_BASEURL=http://your-backend-url
|
||||
|
||||
# 4. 启动 H5
|
||||
pnpm dev:h5
|
||||
|
||||
# 或者启动微信小程序
|
||||
pnpm dev:mp-weixin
|
||||
```
|
||||
|
||||
### 日常开发
|
||||
|
||||
```bash
|
||||
# H5 开发
|
||||
pnpm dev:h5
|
||||
|
||||
# 微信小程序开发
|
||||
pnpm dev:mp-weixin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**祝您开发愉快！** 🎉
|
||||
Reference in New Issue
Block a user