Files
persionalBrand/docs/adr/0015-template-build-time-composition.md
T

2.2 KiB

ADR 0015:模板采用构建时叠加编译

背景

平台需要支持大量行业和视觉风格不同的小程序模板。把所有模板代码放在 apps/miniapp,再通过运行时分支选择,会让壳持续膨胀、模板之间互相污染,也无法可靠验证某个品牌最终打开的页面。

决策

template:dev 采用三层构建时叠加:

  1. apps/miniapp 只提供品牌无关的运行时、通用 UI、公共页面和 TDesign 依赖。
  2. packages/capability-* 提供独立业务流程页面,由模板 manifest 的 requiredCapabilities 声明引入。
  3. packages/template-* 提供完整视觉模板页面、组件、资源和 app.json 窗口配置。

编译器按运行时 → 能力包 → 模板包的顺序复制,并对同路径文件执行显式冲突校验。模板只能通过 overrides 声明替换下层页面或组件目录。最终生成 app.json、project.config.json、runtime-config.js 和 template.runtime.json,产物可直接由微信开发者工具打开。

品牌 slug、API 地址和 AppID 是构建参数;开发构建允许通过 storage 覆盖 API 和品牌,生产构建必须显式提供并使用 HTTPS API。模板切换不在小程序运行时完成,而是在构建时选择模板包。

替代方案

  • 运行时携带全部模板并按 templateKey 分支:代码和资源随模板数量线性膨胀,容易混用,放弃。
  • 运行时下载 WXML/JS 模板:微信小程序安全和编译模型不支持,放弃。
  • 每个模板独立复制完整小程序:公共能力重复、修复无法统一,放弃。

后果

新增模板只需新增 package 和 manifest,不需要改 compiler 或 runtime。模板包需要自行提供 manifest 声明的页面四件套和 tab 资源,编译测试会阻止缺页、缺图标、组件引用或 require 路径错误。后台视觉模板切换不会直接改变已构建小程序,后台切换历史和回滚属于后续治理任务。

迁移计划

先完成阿成、林境两个模板和 booking capability 的迁移,再增加第二行业演练模板。每个新增模板必须通过 compiler 产物校验、模板契约校验和小程序 fixture 检查后才能进入目录 registry。