car-app/启动文档.md

# 小程序启动文档

本文档介绍如何启动小程序的 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
```

---

**祝您开发愉快！** 🎉