本机容器化联调教程

这套方案的目标是：Windows 只负责编辑源码和运行微信开发者工具；PostgreSQL、Redis、Node.js/NestJS、Prisma 都运行在 Linux 容器中。 因此本机行为尽量贴近未来 Linux 服务器，避免把 Windows 的 Node、数据库服务或路径习惯带进部署产物。

先理解两种 Compose 运行方式

目的	命令	特性
日常开发、改代码自动重载	`docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build`	源码挂载进 Linux 开发容器，NestJS 热重载
发布前模拟	`docker compose up -d --build`	使用 `docker/Dockerfile` 的多阶段生产构建，不挂载源码

两种方式共用 PostgreSQL、Redis、迁移文件和 .env；不要同时启动它们。日常使用第一种，准备交付或部署前再使用第二种。

Windows 要运行 node:alpine、postgres:alpine 这类 Linux 镜像，Docker Desktop 底层必须使用 WSL 2、Hyper-V 或 Docker VMM 之一。你不需要在 WSL 里写代码或打开 Ubuntu；它只是 Docker 的 Linux 运行底座。若完全不允许这些虚拟化能力，就只能改用远程 Linux 测试机，无法在 Windows 本机运行 Linux Compose。

一次性安装

在 BIOS/UEFI 确认开启 CPU 虚拟化（Intel VT-x / AMD-V）。
以管理员身份打开 PowerShell，执行 wsl --install；已安装时执行 wsl --update，按提示重启。
安装 Docker Desktop for Windows，首次启动时选择 Use WSL 2 instead of Hyper-V。无需在 WSL 内安装 Node、PostgreSQL 或 Redis。
重启 Docker Desktop 后，在普通 PowerShell 验证：
```
docker version
docker compose version
```

安装依据见 Docker Desktop for Windows 官方文档与 WSL 2 后端说明。

启动后端联调环境

以下命令均在 G:\wordcloud_wechat\wxmp_backend 执行。

创建只属于本机的配置文件（该文件被 Git 忽略）：
```
Copy-Item .env.example .env
```
打开 .env，至少改成下列本机联调值。不要提交 .env，真实微信密钥也不要放入前端。
```
NODE_ENV=development
APP_PORT=3090
JWT_SECRET=dev-only-change-this-to-a-long-random-string
WX_APPID=local-dev-appid
WX_SECRET=local-dev-secret
WX_MOCK_LOGIN=1
```
DATABASE_URL 和 REDIS_URL 可保持示例值：Compose 会在容器内自动改为 postgres、redis 服务地址。

首次先拉取所有公开测试镜像，再构建并启动开发环境：

docker compose -f docker-compose.yml -f docker-compose.dev.yml pull
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
docker compose -f docker-compose.yml -f docker-compose.dev.yml ps

预期 postgres、redis、app 都是 running/healthy。查看后端实时日志：

docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f app

导入 R1 商品初始数据（只需首次，或想恢复演示数据时执行）：

docker compose -f docker-compose.yml -f docker-compose.dev.yml exec app npm run prisma:seed

在浏览器检查：
- http://127.0.0.1:3090/docs：Swagger 接口页
- http://127.0.0.1:3090/api/products：R1 商品列表 JSON

修改 src/ 或 prisma/ 后，开发 Compose 的 app 会热重载；变更依赖或 Dockerfile 后重新执行 up -d --build。停止环境用 docker compose -f docker-compose.yml -f docker-compose.dev.yml down。这不会删除数据库数据卷；需要完全清空数据时才使用 down -v。

微信开发者工具：打开哪里、怎样看到页面

应导入 前端项目根目录：G:\wordcloud_wechat\wechat_wc。

不要导入工作区总目录 G:\wordcloud_wechat，也不要直接导入 dist。原因是前端根目录的 project.config.json 中已经声明 miniprogramRoot: "dist/"；开发者工具从该根目录读取项目配置，再把 dist 当作实际小程序输出。

首次操作如下：

在一个 PowerShell 窗口进入前端目录，安装依赖并创建本机环境文件：
```
cd G:\wordcloud_wechat\wechat_wc
npm ci
Copy-Item .env.example .env
npm run dev:weapp
```
最后一条命令保持运行。Taro 会持续把源码编译到 dist/；它不是服务器，也不需要在 Windows 安装后端 Node。
打开微信开发者工具，选择 导入项目，目录选择 G:\wordcloud_wechat\wechat_wc。若提示 AppID，使用项目已有 AppID；仅查看 UI 也可选择测试号/游客模式（以工具实际选项为准）。
等待终端首次构建完成，在开发者工具点顶部编译。中间的 模拟器 就是小程序运行画面；切换底部或右侧的 Console 看前端异常、Network 看接口请求。以后保存 src 中的文件，Taro 会更新 dist，工具会自动或在点“编译”后刷新。
为本机 HTTP 接口联调，打开开发者工具的 详情 → 本地设置，勾选“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”。仅本机开发使用，提交/真机预览前必须关闭。

前端 .env 已提供：

TARO_APP_API_BASE_URL=http://127.0.0.1:3090

它会在 npm run dev:weapp 编译时注入；src/utils/request.ts 因而请求本机 Docker 后端。更换 .env 后必须重启该 Taro 命令。Taro 环境变量与构建调试方式可参阅 Taro 官方文档和调试文档。

联调检查顺序

浏览器 /docs、/api/products 正常
        ↓
Taro 终端构建成功，dist/ 更新
        ↓
微信开发者工具导入 wechat_wc 并编译
        ↓
Network 中商品请求为 http://127.0.0.1:3090/api/products，状态 200
        ↓
商品页展示 R1 数据

注意：127.0.0.1 仅代表运行开发者工具的这台 Windows 电脑。它适合模拟器，不适合真实手机；真机或他人联调时，应改为可访问的 HTTPS 测试域名，并在微信公众平台配置合法 request 域名。生产环境通常让 Nginx/Caddy 作为 HTTPS 入口，应用、PostgreSQL、Redis 仍留在 Docker 内部网络，不对公网暴露。

6.4 KiB Raw Blame History Unescape Escape