8.3 KiB
8.3 KiB
小程序启动文档
本文档介绍如何启动小程序的 H5 版本、微信小程序版本，以及通过 HBuilderX 启动小程序。
📋 前置要求
环境要求
- Node.js: >= 20
- pnpm: >= 9（必须使用 pnpm，项目已配置强制使用）
- 微信开发者工具（用于调试小程序）
- HBuilderX（可选，用于通过 HBuilderX 启动）
安装依赖
# 进入项目目录
cd yudao-ui-admin-uniapp
# 安装依赖（使用 pnpm）
pnpm install
🚀 方式一：启动 H5 版本
1. 开发环境启动
# 启动 H5 开发服务器（默认端口：5173）
pnpm dev:h5
# 或者直接使用（会默认启动 H5）
pnpm dev
启动成功后，浏览器会自动打开 http://localhost:5173，或者在控制台查看具体的访问地址。
2. 测试环境启动
pnpm dev:h5:test
3. 生产环境启动
pnpm dev:h5:prod
4. 构建 H5 版本
# 开发环境构建
pnpm build:h5
# 测试环境构建
pnpm build:h5:test
# 生产环境构建
pnpm build:h5:prod
构建完成后，文件会输出到 dist/dev/h5 或 dist/build/h5 目录。
📱 方式二：启动微信小程序（命令行方式）
1. 开发环境启动
# 启动微信小程序开发
pnpm dev:mp-weixin
# 或者使用简写
pnpm dev:mp
执行命令后：
- 项目会自动编译到
dist/dev/mp-weixin目录 - 自动打开微信开发者工具（如果已安装）
- 在微信开发者工具中导入项目目录：
dist/dev/mp-weixin
2. 测试环境启动
pnpm dev:mp-weixin:test
# 或
pnpm dev:mp:test
3. 生产环境启动
pnpm dev:mp-weixin:prod
# 或
pnpm dev:mp:prod
4. 构建微信小程序
# 开发环境构建
pnpm build:mp-weixin
# 或
pnpm build:mp
# 测试环境构建
pnpm build:mp:test
# 生产环境构建
pnpm build:mp:prod
构建完成后，文件会输出到 dist/dev/mp-weixin 或 dist/build/mp-weixin 目录。
5. 在微信开发者工具中打开
- 打开微信开发者工具
- 选择"导入项目"
- 选择项目目录：
yudao-ui-admin-uniapp/dist/dev/mp-weixin - 填写 AppID（如果是测试号，可以使用测试号 AppID）
- 点击"导入"
注意事项：
- 如果微信开发者工具没有自动打开，需要手动打开并导入编译后的目录
- 确保在微信开发者工具中设置了正确的 AppID
- 如果是测试，可以使用测试号
🛠️ 方式三：通过 HBuilderX 启动小程序
前置准备
-
下载并安装 HBuilderX
- 下载地址：https://www.dcloud.io/hbuilderx.html
- 推荐使用 HBuilderX 正式版
-
配置 HBuilderX
- 安装微信小程序开发插件（通常已内置）
- 配置微信开发者工具路径（设置 -> 插件配置 -> 微信小程序）
方法一：直接打开项目（推荐使用命令行方式）
注意：本项目基于 unibest 框架，使用 Vite 构建，不需要依赖 HBuilderX。建议使用命令行方式启动（方式二）。
如果你一定要使用 HBuilderX：
- 打开 HBuilderX
- 点击"文件" -> "打开目录"
- 选择项目目录：
yudao-ui-admin-uniapp - 在项目根目录，点击"运行" -> "运行到小程序模拟器" -> "微信开发者工具"
⚠️ 重要提示：
- 本项目使用 Vite 构建，HBuilderX 可能无法正确识别项目结构
- 建议使用命令行方式（
pnpm dev:mp-weixin）编译后，再用 HBuilderX 打开编译后的目录
方法二：打开编译后的目录（推荐）
-
使用命令行编译项目
# 在项目根目录执行 pnpm dev:mp-weixin -
在 HBuilderX 中打开编译后的目录
- 打开 HBuilderX
- 点击"文件" -> "打开目录"
- 选择目录：
yudao-ui-admin-uniapp/dist/dev/mp-weixin - 在 HBuilderX 中点击"运行" -> "运行到小程序模拟器" -> "微信开发者工具"
🔧 环境配置
环境变量文件
项目使用环境变量文件进行配置，配置文件位于 env/ 目录：
.env- 默认配置.env.development- 开发环境配置.env.test- 测试环境配置.env.production- 生产环境配置
常用配置项
# 服务端地址
VITE_SERVER_BASEURL=https://api.tuanbanlv.com
# 应用标题
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
📝 常用命令汇总
开发命令
# 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 # 字节跳动小程序
构建命令
# 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 # 生产环境构建
其他命令
# 代码检查
pnpm lint # ESLint 检查
pnpm lint:fix # ESLint 自动修复
# TypeScript 类型检查
pnpm type-check
# 初始化项目文件
pnpm init-baseFiles
⚠️ 常见问题
1. 提示找不到 pnpm
解决方案：
# 安装 pnpm
npm install -g pnpm
# 验证安装
pnpm -v
2. 微信开发者工具没有自动打开
解决方案：
- 手动打开微信开发者工具
- 选择"导入项目"
- 选择目录：
dist/dev/mp-weixin - 填写 AppID 并导入
3. 端口被占用
解决方案：
- 修改
env/.env.development中的VITE_APP_PORT配置 - 或者关闭占用端口的其他程序
4. 编译失败
解决方案：
# 清理 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
💡 开发建议
-
推荐使用命令行方式启动
- 项目基于 Vite 构建，命令行方式更高效
- 支持热更新，开发体验更好
-
使用 VS Code 开发
- 推荐安装 Vue、TypeScript、UnoCSS 等插件
- 支持代码提示和自动补全
-
调试建议
- H5：直接在浏览器中调试，可使用 Chrome DevTools
- 小程序：使用微信开发者工具进行调试
- 可以使用
console.log进行调试（生产环境会自动移除）
-
代码规范
- 项目已配置 ESLint 和 Prettier
- 提交前会自动检查代码规范
- 建议使用
pnpm lint:fix自动修复代码格式问题
🎯 快速开始
第一次启动
# 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
日常开发
# H5 开发
pnpm dev:h5
# 微信小程序开发
pnpm dev:mp-weixin
祝您开发愉快！ 🎉