常见问题

本地开发

为什么 localhost:7300 和 127.0.0.1:7300 看到的不一样？

它们是两个入口。localhost 是产品站（默认租户），127.0.0.1 是平台控制台。这是 按 Host 分流的结果，详见 Host 分流机制。

访问 /platform 被重定向了？

在产品站 Host 上访问 /platform 会被送去 PLATFORM_URL。控制台只在它自己的 Host 上 开放。

租户子域本地怎么测？

设 TENANT_BASE_DOMAIN=localhost，然后直接访问 http://{slug}.localhost:7300。 浏览器原生把 *.localhost 解析到回环地址，不用改 hosts 文件。

新模块的页面 404？

路由必须挂在 /app/<模块> 下。挂在顶层（如 /site）时，在租户 Host 上会被 CMS 接管——/ 归租户站点，应用区一律走 /app/*。

数据库与迁移

migrate dev 生成了意料之外的 DROP？

它是拿开发库和 schema 比对生成迁移的，开发库的历史痕迹（旧分支、别的项目残留的 表）会变成 DROP。改用离线 diff：把迁移历史重放到一个空的影子库，再和 schema 比， 与开发库现状无关。

能直接删开发库里的表来消除漂移吗？

不能。 删表不改迁移历史，等于制造反向漂移，Prisma 会从「多生成一条 drop」升级成 「必须 reset 整个 schema」。唯一正确的路是让迁移历史与 schema 一致。

外部模块的迁移在哪？

外部模块只声明 prisma/schema.prisma，迁移统一由 apps/server 管理。一个数据库只有 一条迁移历史——模块的 schema 被符号链接进主 schema，迁移由消费方生成。

生产要手动跑迁移吗？

Docker 部署不用，docker/entrypoint.sh 会自动 migrate deploy。非容器部署时手工跑 一次 pnpm --filter server exec prisma migrate deploy。

建站

新站点为什么只有一个首页？

初始化只建一张空白首页，这是刻意的。要定价 / 关于 / 联系页，在 CMS 里自己加； 要产品首页，在站点设置里选模块贡献的版式。

页头怎么没有「免费开始」按钮？

默认不预置页头按钮——它以前指向会员注册，而会员默认未开通，点进去是 403。需要 CTA 就在页头设置里自己加一条。

/docs 能拿来当页面路径吗？

不能，它是文档库的专属路径。语言代码（en、zh-CN）同理。

改完页面访客看不到变化？

编辑器改的是草稿，要在列表里点「发布」才上线。页面和文档都是这个口径。

文档库

怎么写英文版的文档？

新建文档时选语言，同一路径每种语言各存一行。前台按访客语言取对应版本，主语言不带 URL 前缀，其余走 /{locale}/docs。详见 文档库管理。

建好之后能改语言吗？

不能。改语言等于把这一行搬进另一组译文，而那边可能已经有同路径的文档。要换语言就 在目标语言里新建一篇。

导出全部会不会重名？

不会。主语言导出成 faq.md，其余语言导出成 faq.en.md，导入时能认回去。

部署

单租户怎么配？

设 SINGLE_TENANT=true：隐藏控制台、禁止新建租户、所有请求归默认租户。提交前跑 pnpm check:prod-app-env。

默认租户的站点内容需要手工初始化吗？

不需要。服务端启动时自动铺一套已发布的起步站点与文档库，幂等，而且按语言分别判断—— 不会覆盖你改过的内容。

模块

check:modules 报错怎么办？

它校验注册表、租户列、开关、权限、排序、外壳、nav 与 import 边界。按报错逐项修 ——通常是注册表漏登记、模块顺序不对，或 import 了不该 import 的包。

外部模块能依赖别的模块吗？

不能直接 import。跨模块走扩展点（事件、Provider、Slot）。requires 只声明依赖 关系与加载顺序，不给代码级访问。