wechat_wc/docs/微信小程序真机测试说明.md

微信小程序真机测试说明

本文用于指导测试人员在 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，执行：

   cd G:\wordcloud_wechat\wxmp_backend
   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
   

3. 查看容器状态：

   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 登录：

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 窗口，执行：

   cd G:\wordcloud_wechat\wechat_wc
   npm run build:weapp
   

2. 构建成功后，产物位于：

   G:\wordcloud_wechat\wechat_wc\dist
   

3. 当前真机构建应使用线上地址：

   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. 项目目录填写前端源码根目录：

   G:\wordcloud_wechat\wechat_wc
   

   不要选择工作区总目录 G:\wordcloud_wechat。根目录中的 project.config.json 已声明 miniprogramRoot: "dist/"，开发者工具会自动把 dist 作为小程序运行产物。

4. AppID 选择：

   wxad998564cf43a7d9
   

5. 点击“编译”，确认模拟器能打开首页。

6. 点击工具栏“预览”，等待二维码生成。

7. 使用已登录该小程序的微信扫描二维码，在手机上打开预览版本。

六、真机功能测试清单

建议按以下顺序测试，并在每一步记录结果：

序号	操作	预期结果
1	启动小程序	首页正常显示，无白屏或启动异常
2	打开“商品”页	显示后端返回的在售商品列表
3	下拉刷新商品页	请求成功，列表无重复或空白
4	点击商品	商品详情、价格、规格、图片正常显示
5	返回首页	首页商品数据正常显示
6	打开“设计清单”	已登录时可读取服务端清单；未登录时提示登录
7	新增、编辑、删除地址	地址操作成功，默认地址状态正确
8	进入 DIY 并保存设计	设计清单状态和内容正常更新
9	提交订单	能创建订单并显示服务端计算的金额
10	进入支付	若未配置微信支付，显示“支付未配置”等明确提示，不应假装支付成功

商品目录重点验收：页面显示的商品必须来自 GET /api/products 和 GET /api/products/:id，不能只显示前端写死数据。可在测试数据库中修改一个商品价格，再重新进入商品页，确认页面价格同步变化。

七、如何确认手机确实访问了后端

在微信开发者工具的“调试器 → Network”中查看请求，商品页至少应看到：

GET https://wxbackend.tokenleaping.com/api/products?page=1&pageSize=20
GET https://wxbackend.tokenleaping.com/api/products/{商品ID}

响应状态应为 200，响应体应包含：

{
  "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 使用以下转发关系：

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；本机空配置只能测试公开接口
词云或支付无法完成	检查对应外部服务和密钥；未配置时属于预期限制

十、测试记录模板

测试日期：
测试人员：
前端提交：
后端提交：
手机型号 / 微信版本：
后端地址：https://wxbackend.tokenleaping.com

商品列表：通过 / 不通过
商品详情：通过 / 不通过
地址管理：通过 / 不通过
设计清单：通过 / 不通过
订单创建：通过 / 不通过
支付：已配置并通过 / 未配置 / 失败
备注：