支付网关：部署与上线
支付网关是独立的前端工程，构建产物是纯静态文件，部署方式与 Web 管理端一致（静态托管 + 接口反代）。它的特殊性在域名契约：收款链接、回跳与认证回调地址都由后端按支付网关域名生成，部署域名要与平台配置对齐。
构建
- Node 22+ 与 pnpm 10+ 环境；
- 构建产物为纯静态文件（
dist/），生产构建自动移除调试控制台输出。
关键构建配置（写死在环境文件里，按需修改后构建）：
| 配置 | 说明 |
|---|---|
| 后端接口地址 | 生产留空 = 使用相对路径请求，靠同域反代转到后端（推荐） |
| 接口前缀 | 固定 /api/，请求形如 https://你的域名/api/... |
部署四要点
静态托管：构建产物交给 nginx 等静态服务器，与其他前端（Web 管理端）互不依赖、可分开部署；
接口反代：同域下把
/api/反向代理到后端服务（与管理端同策略），无需跨域配置：nginxlocation /api/ { proxy_pass http://后端服务地址/; }SPA 回退：所有路径回退到
index.html——网关上的地址是/cashier/xxx、/h/xxx、/auth/xxx这样的深路径，刷新与直达都不能 404：nginxlocation / { try_files $uri $uri/ /index.html; }HTTPS：面向付款人的页面必须 HTTPS，证书配在 nginx 层。
域名契约（重点）
支付网关的页面地址大部分是后端生成给通道、付款人和登录用户的，不是前端自己拼的：
| 地址 | 谁用 | 生成时机 |
|---|---|---|
收款链接 /cashier/...、/h/...、/aggregate/... | 付款人 | 预下单 / 生成码牌时返回给商户系统 |
支付结果页 /pay-result/{交易号} | 付款人 | 配置了回跳的支付，通道处理完跳转 |
转账确认页 /transfer-confirm/{转账单号} | 收款人 | 发起微信转账时生成 |
| 认证回跳 | 付款人 | 微信网页授权域名 / 支付宝授权回调地址登记的就是网关域名 |
三方登录透传入口 /auth/oauth-callback/... | Web 端登录用户 | 跳转型平台登录 / 绑定回调统一落网关域名 |
因此 支付网关必须部署在平台的支付网关域名之下（该域名在后端「端点配置」维护），后端生成地址、前端提供页面，两边对得上才不会 404。部署前与后端侧的网关域名配置核对一致；认证与透传的机制见认证与中转。
与收银配置的联动
支付网关上线后，收银台展示效果还依赖两处配置（页面本身不用改）：
- 商户的收银台配置：支付方式列表、推荐与锁定（见商户端文档）；
- 域名验证：微信侧 JSAPI 支付需要完成域名归属验证（校验文件上传），见通道对接 - 域名校验文件。
常见部署问题
| 现象 | 原因 |
|---|---|
| 直达链接 / 刷新 404 | 没配 SPA 回退（try_files ... /index.html） |
| 页面开了但请求全失败 | /api/ 反代没配或指错后端 |
| 付款成功后回跳 404 | 部署域名与后端支付网关域名配置不一致 |
| 三方登录后跳 404 / 跳不回发起端 | 端点配置的「支付网关前端地址」与实际部署域名不一致 |
| 支付认证报域名未登记 / 回调不合法 | 开放平台登记的授权域名与支付网关域名不一致 |
| 电脑打开是手机版页面 | 正常按 UA 分发；确认链接没带 ?device=mobile 参数 |
| 微信内付款提示域名未验证 | 域名校验文件未上传或支付目录未配置 |