237 lines
8.7 KiB
Markdown
237 lines
8.7 KiB
Markdown
# 微信小程序真机测试说明
|
||
|
||
本文用于指导测试人员在 Windows 开发机上启动后端、构建前端，并通过微信开发者工具预览到真实手机。测试重点是确认：小程序页面能够通过 HTTPS 访问后端接口，商品、地址、设计清单和订单等页面可以正常联调。
|
||
|
||
## 一、测试环境
|
||
|
||
| 项目 | 配置 |
|
||
| --- | --- |
|
||
| 前端源码 | `G:\wordcloud_wechat\wechat_wc` |
|
||
| 前端导入目录 | `G:\wordcloud_wechat\wechat_wc` |
|
||
| 后端源码 | `G:\wordcloud_wechat\wxmp_backend` |
|
||
| 小程序 AppID | `wxad998564cf43a7d9` |
|
||
| 真机后端地址 | `https://wxbackend.tokenleaping.com` |
|
||
| 本机 Docker 后端地址 | `http://127.0.0.1:3090` |
|
||
| 商品图片地址 | `https://wordcloudwechat.oss-cn-hangzhou.aliyuncs.com` |
|
||
|
||
说明：`127.0.0.1` 只代表当前 Windows 电脑。真实手机不能通过这个地址访问电脑上的 Docker 容器；真机应使用可公开访问的 HTTPS 域名。
|
||
|
||
## 二、启动本机 Docker 后端
|
||
|
||
本步骤用于确认后端和数据库本身正常，也可供微信开发者工具模拟器联调。
|
||
|
||
1. 启动 Docker Desktop，确认左下角显示 Engine running。
|
||
2. 打开 PowerShell，执行：
|
||
|
||
```powershell
|
||
cd G:\wordcloud_wechat\wxmp_backend
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
|
||
```
|
||
|
||
3. 查看容器状态：
|
||
|
||
```powershell
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml ps
|
||
```
|
||
|
||
预期 `wxmp-app`、`wxmp-postgres`、`wxmp-redis` 均为运行状态，其中数据库和 Redis 应显示 `healthy`。
|
||
|
||
4. 在浏览器检查本机接口：
|
||
|
||
- `http://127.0.0.1:3090/health`
|
||
- `http://127.0.0.1:3090/docs`
|
||
- `http://127.0.0.1:3090/api/categories`
|
||
- `http://127.0.0.1:3090/api/products?page=1&pageSize=20`
|
||
- `http://127.0.0.1:3090/api/products/penbox`
|
||
|
||
`/health` 和商品接口返回 HTTP 200，且响应中有 `code: 0`，即可继续测试。
|
||
|
||
### 本机登录配置
|
||
|
||
本机 Docker 若只用于开发者工具模拟器联调，可在后端 `.env` 使用本地 mock 登录：
|
||
|
||
```env
|
||
WX_APPID=local-dev-appid
|
||
WX_SECRET=local-dev-secret
|
||
WX_MOCK_LOGIN=1
|
||
```
|
||
|
||
这是项目《本机容器化联调教程》规定的开发配置，不代表真实微信登录。真实手机登录时，必须改为线上服务器中的真实 `WX_APPID` 与 `WX_SECRET`，并将 `WX_MOCK_LOGIN` 留空；AppSecret 不能提交到 Git。
|
||
|
||
## 三、构建微信小程序前端
|
||
|
||
1. 打开新的 PowerShell 窗口，执行：
|
||
|
||
```powershell
|
||
cd G:\wordcloud_wechat\wechat_wc
|
||
npm run build:weapp
|
||
```
|
||
|
||
2. 构建成功后，产物位于：
|
||
|
||
```text
|
||
G:\wordcloud_wechat\wechat_wc\dist
|
||
```
|
||
|
||
3. 当前真机构建应使用线上地址：
|
||
|
||
```text
|
||
https://wxbackend.tokenleaping.com
|
||
```
|
||
|
||
修改环境变量或配置后，必须重新执行构建；微信开发者工具不会自动读取源码目录中的环境变量。
|
||
|
||
## 四、配置微信公众平台合法域名
|
||
|
||
登录小程序管理后台，在“开发 → 开发管理 → 开发设置 → 服务器域名”中配置：
|
||
|
||
| 类型 | 域名 |
|
||
| --- | --- |
|
||
| request 合法域名 | `https://wxbackend.tokenleaping.com` |
|
||
| downloadFile 合法域名 | `https://wordcloudwechat.oss-cn-hangzhou.aliyuncs.com` |
|
||
| uploadFile 合法域名 | 使用 COS 直传时配置同一 OSS 域名 |
|
||
|
||
配置要求：
|
||
|
||
- 只填写 HTTPS 域名，不填写接口路径、端口、`/health` 或 `/api`。
|
||
- HTTPS 证书必须有效，域名证书需覆盖 `wxbackend.tokenleaping.com`。
|
||
- 修改服务器域名后，重新编译并重新预览小程序。
|
||
|
||
开发者工具中的“不校验合法域名”只适合模拟器临时调试，不能替代公众平台的正式域名配置。
|
||
|
||
## 五、导入开发者工具并预览
|
||
|
||
1. 打开微信开发者工具。
|
||
2. 选择“导入项目”。
|
||
3. 项目目录填写前端源码根目录：
|
||
|
||
```text
|
||
G:\wordcloud_wechat\wechat_wc
|
||
```
|
||
|
||
不要选择工作区总目录 `G:\wordcloud_wechat`。根目录中的 `project.config.json` 已声明
|
||
`miniprogramRoot: "dist/"`，开发者工具会自动把 `dist` 作为小程序运行产物。
|
||
|
||
4. AppID 选择：
|
||
|
||
```text
|
||
wxad998564cf43a7d9
|
||
```
|
||
|
||
5. 点击“编译”，确认模拟器能打开首页。
|
||
6. 点击工具栏“预览”，等待二维码生成。
|
||
7. 使用已登录该小程序的微信扫描二维码，在手机上打开预览版本。
|
||
|
||
## 六、真机功能测试清单
|
||
|
||
建议按以下顺序测试，并在每一步记录结果：
|
||
|
||
| 序号 | 操作 | 预期结果 |
|
||
| --- | --- | --- |
|
||
| 1 | 启动小程序 | 首页正常显示，无白屏或启动异常 |
|
||
| 2 | 打开“商品”页 | 显示后端返回的在售商品列表 |
|
||
| 3 | 下拉刷新商品页 | 请求成功，列表无重复或空白 |
|
||
| 4 | 点击商品 | 商品详情、价格、规格、图片正常显示 |
|
||
| 5 | 返回首页 | 首页商品数据正常显示 |
|
||
| 6 | 打开“设计清单” | 已登录时可读取服务端清单；未登录时提示登录 |
|
||
| 7 | 新增、编辑、删除地址 | 地址操作成功，默认地址状态正确 |
|
||
| 8 | 进入 DIY 并保存设计 | 设计清单状态和内容正常更新 |
|
||
| 9 | 提交订单 | 能创建订单并显示服务端计算的金额 |
|
||
| 10 | 进入支付 | 若未配置微信支付，显示“支付未配置”等明确提示，不应假装支付成功 |
|
||
|
||
商品目录重点验收：页面显示的商品必须来自 `GET /api/products` 和 `GET /api/products/:id`，不能只显示前端写死数据。可在测试数据库中修改一个商品价格，再重新进入商品页，确认页面价格同步变化。
|
||
|
||
## 七、如何确认手机确实访问了后端
|
||
|
||
在微信开发者工具的“调试器 → Network”中查看请求，商品页至少应看到：
|
||
|
||
```text
|
||
GET https://wxbackend.tokenleaping.com/api/products?page=1&pageSize=20
|
||
GET https://wxbackend.tokenleaping.com/api/products/{商品ID}
|
||
```
|
||
|
||
响应状态应为 `200`，响应体应包含：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
如果请求地址仍然是 `127.0.0.1:3090`，说明前端没有使用真机构建配置，需要重新检查环境变量并执行 `npm run build:weapp`。
|
||
|
||
## 八、本机 Docker 与真机的关系
|
||
|
||
本机 Docker 只负责在 Windows 上运行 Linux 容器中的后端、PostgreSQL 和 Redis。它不会自动获得公网 HTTPS 地址。
|
||
|
||
有两种测试方式：
|
||
|
||
### 方式 A：直接测试线上 HTTPS 服务（推荐）
|
||
|
||
- 前端构建地址使用 `https://wxbackend.tokenleaping.com`。
|
||
- 微信开发者工具生成预览二维码。
|
||
- 手机通过互联网访问线上后端。
|
||
- 本机 Docker 只用于本地接口检查，不影响手机请求。
|
||
|
||
### 方式 B：让手机测试本机 Docker 代码
|
||
|
||
需要额外配置内网穿透或 FRP：
|
||
|
||
1. Windows 上的 `frpc` 将本机 `3090` 转发到服务器上的 FRP 服务端。
|
||
2. 服务器反向代理将 HTTPS 域名转发到 FRP 通道。
|
||
3. 前端仍构建为 `https://wxbackend.tokenleaping.com`。
|
||
4. 确认微信公众平台合法域名已配置，并重新预览。
|
||
|
||
仅启动 Docker Desktop，不能让真实手机直接访问 `127.0.0.1`。
|
||
|
||
### 当前项目的 FRP 映射
|
||
|
||
本项目提供的 `frpc.toml` 使用以下转发关系：
|
||
|
||
```toml
|
||
serverAddr = "43.155.206.17"
|
||
serverPort = 7000
|
||
|
||
[[proxies]]
|
||
name = "wxbackend"
|
||
type = "tcp"
|
||
localIP = "host.docker.internal"
|
||
localPort = 3090
|
||
remotePort = 3090
|
||
```
|
||
|
||
对应含义是：FRP 客户端容器把 Windows 主机的 `3090` 转发到服务器 `3090`；服务器上的 HTTPS 反向代理再将 `wxbackend.tokenleaping.com` 转到该端口。`frpc.toml` 中的认证 token 仅保存在本机文件，不要提交到 Git。
|
||
|
||
## 九、常见问题
|
||
|
||
| 现象 | 处理方法 |
|
||
| --- | --- |
|
||
| `request:fail url not in domain list` | 在公众平台添加 request 合法域名，重新编译并预览 |
|
||
| `ERR_CERT` 或 TLS 错误 | 检查 HTTPS 证书、域名解析和服务器时间 |
|
||
| 手机请求连接被拒绝 | 不要使用 `127.0.0.1`；确认线上域名或 FRP 转发正常 |
|
||
| 模拟器正常、手机白屏 | 检查真机构建地址和服务器域名配置，查看 Network 错误 |
|
||
| 商品图片不显示 | 将 OSS 域名加入 downloadFile 合法域名，并检查图片 URL |
|
||
| 登录失败 | 检查线上后端的微信 AppID、AppSecret；本机空配置只能测试公开接口 |
|
||
| 词云或支付无法完成 | 检查对应外部服务和密钥；未配置时属于预期限制 |
|
||
|
||
## 十、测试记录模板
|
||
|
||
```text
|
||
测试日期：
|
||
测试人员：
|
||
前端提交：
|
||
后端提交：
|
||
手机型号 / 微信版本：
|
||
后端地址：https://wxbackend.tokenleaping.com
|
||
|
||
商品列表：通过 / 不通过
|
||
商品详情：通过 / 不通过
|
||
地址管理：通过 / 不通过
|
||
设计清单：通过 / 不通过
|
||
订单创建：通过 / 不通过
|
||
支付：已配置并通过 / 未配置 / 失败
|
||
备注：
|
||
```
|