PAYATHON 2026

启用 Jetpack debug mode 后 WooPayments 仍要求公共域名

支付老李

结论

JETPACK_DEV_DEBUG 无法让 WooPayments 在完全离线的 localhost 环境中工作。它只会让 Jetpack 进入开发或调试模式，跳过或关闭部分依赖 WordPress.com 的功能。它不会让本机地址变成可公开访问的网站，也不能模拟 WooPayments 所需的远程连接。

WooPayments 的账户开通、支付请求和状态同步都依赖远程服务。由于这些服务无法回调 localhost、127.0.0.1 或局域网 IP，页面仍会显示：

Your site host “localhost” is on a private network. Jetpack can only connect to public sites.

如需完整测试 WooPayments，通常要通过 HTTPS 隧道为本地站点生成一个临时公共域名，再完成连接并启用 WooPayments 测试模式。

为什么 debug mode 不能解决问题

下面这项配置：

define( 'JETPACK_DEV_DEBUG', true );

主要用于在本地开发 Jetpack 功能。它不能：

  • 为 localhost 分配公共域名；
  • 代理 WooPayments 的支付接口；
  • 允许远程服务访问本机；
  • 模拟 Jetpack 或 WordPress.com 连接；
  • 接收 WooPayments 的服务器回调和状态通知。

这与 WooPayments 的实际要求并不一致。WooPayments 需要有效的远程连接，而 Jetpack 开发模式允许站点在没有正常连接的情况下运行部分 Jetpack 功能。

因此，JETPACK_DEV_DEBUG 不能作为 WooPayments 的本地测试开关。

推荐方案：为本地站点建立 HTTPS 隧道

可以使用能生成临时公开链接的开发工具，例如：

  • Local 的 Live Link；
  • ngrok；
  • Cloudflare Tunnel；
  • 其他能将本地 HTTP 服务映射到公共 HTTPS 地址的工具。

假设隧道生成了以下地址：

https://example-tunnel.example

这个地址必须能从互联网正常打开本地 WordPress 网站，不能只显示隧道服务的错误页或身份验证页面。

如果需要，可以暂时在 wp-config.php 中指定公开地址：

define( 'WP_HOME', 'https://example-tunnel.example' );
define( 'WP_SITEURL', 'https://example-tunnel.example' );

这两项配置必须放在下面这行之前：

/* That's all, stop editing! Happy publishing. */

是否要修改 WP_HOME 和 WP_SITEURL，要看本地开发工具如何处理代理域名。有些工具会自动重写 URL，这种情况下不要重复配置。

完整测试步骤

  1. 启动本地 WordPress 和 WooCommerce，确认普通结账页面可以访问。
  2. 建立一个指向本地 Web 服务的公共 HTTPS 隧道。
  3. 通过隧道地址打开 WordPress 后台。
  4. 检查“站点地址”和“WordPress 地址”，确认它们没有继续指向 localhost。
  5. 暂时删除或注释 JETPACK_DEV_DEBUG：
// define( 'JETPACK_DEV_DEBUG', true );
  1. 重新连接 Jetpack 或 WordPress.com。如果原来的连接绑定了 localhost，可能需要先断开，再重新连接。
  2. 完成 WooPayments 测试账户设置。
  3. 在 WooPayments 设置中启用测试模式。
  4. 使用 WooPayments 提供的测试卡完成结账。

常用的成功付款测试卡号是：

4242 4242 4242 4242

有效期可以填写未来日期，CVC 可以填写符合格式的测试值，例如：

Expiry: 12/30
CVC: 123

测试卡只能在明确启用测试模式后使用。不要在实时模式中提交测试卡，也不要用真实银行卡测试开发站点。

常见问题

隧道地址可以打开，但仍提示私有网络

检查 WordPress 实际识别的地址是否仍然是：

http://localhost

同时确认反向代理正确传递了 HTTPS 状态。否则，WordPress 可能生成 HTTP 链接、出现重定向循环，或者继续向 WooPayments 报告本机地址。

每次启动隧道后地址都会变化

免费隧道服务通常每次都会生成新的随机域名。域名变化后，可能需要重新设置 WP_HOME 和 WP_SITEURL，并再次检查 Jetpack 和 WooPayments 的连接状态。

如果需要长期开发，可以使用固定的隧道域名，或者单独搭建一个公开测试站点。

能否完全断网测试 WooPayments

完全断网时，无法完成 WooPayments 的真实端到端流程。即使启用了测试模式，支付请求仍要发送到远程测试服务。

离线环境只能测试 WooCommerce 的页面布局、购物车逻辑和自定义结账代码，不能验证 WooPayments 的授权、失败处理、退款和异步状态更新。

注意事项

  • 公共隧道会暂时把本地站点暴露到互联网。请使用强管理员密码，不要放入真实客户数据。
  • 不要在开发环境中启用 WooPayments 实时模式。
  • 测试完成后，删除临时添加的 WP_HOME 和 WP_SITEURL 配置，恢复本地域名。
  • 如果使用隧道仍无法完成账户开通，可以改用公开的 staging 站点。对 WooPayments 而言，这通常比经常变化的临时域名更稳定。
  • WCPAY_DEV_MODE 等用于 WooPayments 插件开发环境的配置，不等于商户测试模式。不要仅为了测试结账而随意启用。

备注：内容仅供参考。