technical

WSL2 开发与部署主路径

说明为什么 Toolplane 把 Ubuntu / WSL2 设为默认运行链路,以及现在已经固定的 `dev / build / preview / deploy` 命令入口、staging 域名和 Windows fallback 规则。

Audience

开发者 / 部署维护

Updated

2026-03-28

Source

docs/wsl-delivery.zh-CN.md

当前标准

  • 默认 dev / build / lint / preview / deploy / upload / D1 迁移 / seed / typegen 全部走 Ubuntu / WSL2
  • 当前 staging 域名是 toolplane.fluentreact.com
  • deploy:staging 默认会把 OpenNext R2 incremental cache 上传并发固定为 5,避免 Wrangler bulk put 的瞬时 fetch failed
  • Windows 原生链路只保留给应急排查和对照验证

为什么现在切换

OpenNext 与 Cloudflare Workers 这条链路对 Linux 运行时更友好,WSL2 更接近最终线上环境。

之前已经出现过 Windows 原生上传成功但线上 Worker 全站 500 的情况,因此必须把 release proof 切到 WSL2 主路径。

当前命令入口

  • npm run dev -> npm run dev:wsl
  • npm run build -> npm run build:wsl
  • npm run preview -> npm run preview:wsl -> npm run preview:staging:wsl
  • npm run deploy -> npm run deploy:wsl -> npm run deploy:staging:wsl
  • npm run upload / d1:migrate:staging / d1:seed:staging / cf-typegen 都已固定到显式 :wsl alias
  • 模块四 Day 1 到 Day 5 都已完成;模块五 Day 1 到 Day 10 也已收口,Settlement 已共享 ledger stage / revenue share / payout policy / hold profile,developer / marketplace / settlement 的模块入口与文档入口也已统一暴露,扩展框架验收文档现已入库,下一轮真正实现优先级锁定为组织、成员、权限,其次才是 Auth / RBAC enforcement