Files
persionalBrand/docs/adr/0025-build-output-stack-masking.md
T
que01 9ad2776515 feat: 遮蔽产物中的 Taro 指纹
H5 预览与小程序产物会带出 taro_tmpl、taro-*-core、taro.js、--taro-button-height、
project.config.json 的 projectname 等指纹,而 Taro 4.3 没有隐藏这些名称的配置。
改为在 build:h5、build:weapp、build:preview 之后按 apps/taro/config/mask.config.json
做构建后处理:

- 同一张替换表同时作用于文件名与文本内容,重命名后引用保持同步,长度 ≥ 40 的 base64/哈希片段原样保留;
- 遮蔽后仍命中 forbidden 词表时构建失败,并把 project.config.json 的 projectname/description 中性化;
- dev:h5、dev:preview 保持原始命名,便于本地调试;改架构名只改 mask.config.json;
- 产物契约测试先用 unmask() 还原再断言,浏览器测试选择器写成 :is(<源码名>, <遮蔽名>)。

取舍与迁移见 docs/adr/0025-build-output-stack-masking.md。
2026-10-13 23:03:32 +08:00

38 lines
3.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 0025 构建产物技术栈遮蔽
## Context
模板预览(H5)与微信小程序产物都是外部可获取的材料:预览页面可以打开 DevTools 查看 DOM 与资源,小程序包也能从微信侧下载后反编译。Taro 的指纹在产物中大量出现且没有官方开关:`taro_tmpl`、`base.wxml`、`utils.wxs`、`comp.*`、`taro.js`、`taro-*-core` 自定义元素、`taroWindowProvider`、`taro_tabbar_page`、`--taro-button-height`、`project.config.json` 的 `projectname` 等。竞争对手据此可以判断预览与小程序都由 Taro 生成。
Taro 4.3 没有隐藏这些名称的配置项。名称分别硬编码在 `@tarojs/plugin-platform-weapp`、`@tarojs/vite-runner`、`@tarojs/runtime` 内部;官方 hook(`modifyBuildAssets`、`modifyMiniConfigs`、`modifyRunnerOpts`)只能改写构建产物与配置,覆盖不到运行时内部硬编码的标识符。
## Decision
- 在 `apps/taro` 的生产构建脚本末尾增加构建后处理:`apps/taro/config/mask-taro.cjs` 读取 `apps/taro/config/mask.config.json`,对 `dist/<templateKey>/weapp`、`dist/<templateKey>/h5`、`dist/template-preview/h5` 做确定性改名。
- 同一张替换表同时作用于文件名和文本内容,因此 `taro.js` 与其引用会一起变成 `appkit.js`,`taro_tmpl` 与页面里的引用也保持同步,不需要维护两份映射。
- 只遮蔽 Taro 相关标识符;vite、rollup、rolldown 等通用打包工具的名称属于行业通用信息,不做处理。
- 长度 ≥ 40 的不透明串(内嵌 base64、摘要)保持原样,避免误改数据。
- 遮蔽后仍存在 `forbidden` 词表命中时构建失败(退出码 1),因此产物不会静默泄露。
- `project.config.json` 的 `projectname`、`description` 由配置中性化。
- 源码与开发构建不改名:`dev:h5`、`dev:preview` 输出保留 Taro 原始命名,便于本地调试;只有 `build:h5`、`build:weapp`、`build:preview` 产物会遮蔽。
## Alternatives
- 用 `pnpm patch` 修改 `@tarojs/*` 包内硬编码名称:升级即失效,且改动面覆盖多包,维护成本高。
- 只使用官方 hook 改产物:无法覆盖运行时内部标识符,指纹仍会残留。
- fork Taro 并发行私有包:收益有限,却把框架升级变成长期负担。
- 完全隐藏以“这是前端工程”为目标的其它工具:与目标无关,徒增维护面。
## Consequences
- 产物中的名称与源码名称不一致,因此产物契约测试必须先 `unmask()` 再断言,浏览器测试的选择器使用 `:is(<源码名>, <遮蔽名>)` 同时接受两种命名。
- 新增会出现在产物里的 Taro 标识符时,需要同时更新 `mask.config.json` 的 `replacements` 与 `forbidden`,否则构建会因为 `forbidden` 命中而失败(这是期望行为)。
- 必须通过 `pnpm --filter @personal-brand/taro build:*` 构建。直接执行 `taro build` 不经过遮蔽。
- 改架构名只改 `mask.config.json`,不需要改构建脚本、测试或文档中的映射。
## Migration Plan
1. 默认 `enabled: true`;出现遮蔽引起的问题时可临时置为 `false` 让构建脚本跳过处理,产物回到未遮蔽状态。
2. 新增模板或升级 Taro 后先跑一次 `build:weapp` 与 `build:preview`,确认构建脚本的指纹检查通过。
3. 需要复核某次产物是否干净时执行 `TEMPLATE_KEY=<key> node config/mask-taro.cjs weapp --check`;它只检查、不修改。