常见问题

这一页按"现象 → 原因 → 怎么办"组织，只收真会卡住人的问题，来源是历轮事故备案和评审高频提问。找不到的主题先查文档地图；仍然找不到的，以代码和测试为准。

环境与启动

Q：npm install 报 peer 依赖冲突？ vitest 3 和 @angular/build 的 peer 范围冲突，是备案过的已知项（RK-09），CI 也用同款方案：npm install --legacy-peer-deps。不要用 --force，那会掩盖别的问题。

Q：postinstall 报 @gmap 链接错误？scripts/link-gmap.mjs 是幂等守卫：姊妹仓 ../gissdk_onemap 不在场就静默跳过。只有 ng-mfe / GISSDK 联调才需要姊妹仓，editor 独立开发不受影响。

Q：dev server 起不来，说端口被占？ dev 钉死 :4230（strictPort）。先查谁占着：

lsof -tiTCP:4230 -sTCP:LISTEN | xargs kill

十有八九是上一次没关干净的 dev server。这个陈旧进程还是 e2e 整批假红的第一嫌疑（见下文测试节）。

Q：地图画布空白？ dev 默认装载本地 klokantech 底图，外网端点拉取失败会逐级回退到内置离线演示样式（editor/public/styles/offline-demo-cn.json）。排查顺序：浏览器控制台网络面板看哪个请求失败 → 确认 /mock/* 端点有没有响应（清单在 editor/mock/README.md）→ 若是自建托管环境，看下文 worker 问题。

开发

Q：现在到底用 RxJS 还是 Signals？ 都要，分工明确（ADR-15 裁决）：同步派生用 signal/computed；新增异步流（请求、定时器、事件编排）用 RxJS 管道，出口 AsyncPipe 或 toSignal；手写 .subscribe( 必须同行配 takeUntilDestroyed，架构测试文本扫描强制。存量 signals 照常运行，按阶段表渐进迁移，明细在 DEVELOPMENT-GUIDE §2。

Q：改了组件成员名，测试全绿但界面坏了？ 这个工具链没有模板类型检查通道：模板引用不存在的类成员，tsc 和 vitest 都抓不到，运行时静默空白。改公共成员名必须同步 grep 模板，或者补成员存在性守卫测试。同类盲区还有"模板用了 ms-* 组件但 @Component 缺 imports"（静默渲染为空），用 template-imports-guard 对冲。三类盲区详见测试策略。

Q：弹层里的投影内容（ng-content）不显示？ ng-content 不许被 @if / @for / @switch 包裹。Angular 的投影内容在初始化时一次性创建，条件插槽永远不会渲染，还不报错。对冲是壳组件无条件单一 ng-content + 全模板字节钉 + e2e 兜底（R6.5 M4 事故实证）。

Q："放弃草稿"之后恢复提示又弹出来，死循环？ autosave 的 effect 分不清用户编辑和程序化装载。任何装载入口必须先 suppressNextSave() 布防，否则刚装载的内容马上又被写进草稿。遇到这个现象说明有一条装载链忘了布防，是需要立项修复的缺陷，不是正常行为。

Q：跨组件触发另一个面板的动作，怎么写？ 走 UiService 的计数信号通道（如 sourcesAddRequest、treeScrollTarget）：计数而不是布尔值，组件未挂载期间请求不丢、消费即焚。不要互调组件方法，也不要新开布尔开关信号。

Q：雪、雨面板为什么全是禁用态？ MapLibre 当前没有 snow/rain 的样式根属性和运行时 API，这是有意禁用并横幅备案的。值只存界面档（ms-config 的 globals 段），不下发。引擎支持后会解除。

Q：测试文件放哪？editor/tests/ 镜像树，mock 管线的测试在 editor/mock/。src 下出现 *.test.ts 会被 migrate 脚本自动迁走。

测试红了怎么排查

单点失败看断言就行；整批红、间歇红、莫名其妙红，按这个路径走：

补充两条：

Q：覆盖率本地怎么看？和文档数字对不上？ 本地 npx vitest run --coverage（npm test 默认不加载 coverage 配置）。快照数字以 CI 与轮次记录为准，本站不维护。

Q：仓里三套 e2e 是什么关系？tools/e2e.mjs（17 套，回归门禁）、e2e-tests/（11 套，用例文档双向匹配门禁）、e2e-audit/（395 例人工审计，不进门禁、退出码恒 0）。详见测试策略的 e2e 一节。

构建与部署

Q：生产环境 worker 报 MIME 错误 / 加载失败？ 确认 dist 里 assets/maplibre-gl-worker.js 存在且以 .js 落盘（有意决策，ADR-09）。自建静态服务要给 .mjs/.js 正确的 text/javascript MIME，或者直接用 Rust server（内置）。

Q：生产环境 /mock/ 全部 404？* mock 是 dev/preview 的 vite 插件，构建产物里没有。生产由 Rust server 承接（cargo run --release -- --static ../editor/dist）或反代转发，详见构建与部署。

Q：升级 maplibre-gl 后构建抛"资产改写失败"？ worker 资产插件对发行结构有字面量假设，上游漂移就抛错——这是防静默劣化的设计。按报错同步 vite.config.ts 的 WORKER_ASSETS，不要绕过插件。

Q：能部署在子路径下吗（如 /studio/）？ 未支持：资源按绝对路径 /assets/... 引用。真有需要，先评审 worker URL 与 mock 端点前缀两处。

Q：server 的运行时数据存哪？server-data/（gitignored），上传的字体、图标、数据档案都在里面，重启不丢。

文档站

Q：文档站的 plantuml 流程图怎么渲染的？ 构建期处理：Markdown 里语言标注为 plantuml 的代码块（内容以 @startuml 开头、@enduml 结尾）会被 VitePress 插件截获，调本机 plantuml 命令生成白底 SVG，按内容哈希存进 public/diagrams/，页面里内嵌为 <img>。本机没装 plantuml 时退回普通代码块，站点照样能建——所以"图没渲染出来"先跑 plantuml -version 确认工具在不在。SVG 按哈希缓存，改了图的源码，下次构建自动重渲。

Q：docs-site 构建失败说死链？ 有意为之：构建即全站死链检查。改文件名或删页面时，把全站指向它的链接一起改掉再构建。

Q：想找某个事实的权威出处？ 先查文档地图登记表；找不到就以代码与测试为准，并回填登记。

进度与历史

Q：最新进度在哪看？ 轮次链索引在 docs/notes/roadmap.md 文末；轮次明细在 editor/docs/refactor/REFACTOR-CHANGELOG.md（正序排，最新翻到文末）；当前进行时的简化重构见演进指南。

Q：历史第三方评估报告（ChatGPT_REPORT 等）哪去了？ 已删除：结论由 R6 治理轮和 roadmap 消化，原文查 git 历史。现状以代码、roadmap 索引和本站为准。

Q：为什么没有英文像素对比了？ 2026-09-19 全量汉化（用户决策）后英文基准封存，视觉回归改为中文基线 11 状态（ADR-11）。

Q：发版前要人工验收吗？ 按 docs/spec/full-requirements/manual-acceptance.md（22 域约 90 用例）逐项过一遍并填记录，P0 域须全绿。建议先装载 tools/fixtures/ 冻结样式，避免默认样式随网络漂移干扰验收。