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。
This commit is contained in:
que01 committed 2026-10-13 23:03:32 +08:00
1 parent 53713e5935
commit 9ad2776515
13 files changed
+382 -10

No files matched your search

@@ -0,0 +1,37 @@
# 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`;它只检查、不修改。
+2
View File
@@ -66,6 +66,8 @@ pnpm preview:templates
VITE_APP_BASE_PATH=/ ADMIN_PORT=3000 pnpm --filter @personal-brand/admin dev
```
预览与小程序产物在构建时遮蔽 Taro 标识符(见 [ADR 0025](adr/0025-build-output-stack-masking.md)),因此生产预览与小程序包只通过包内构建脚本产出:`pnpm build:admin:preview`、`pnpm --filter @personal-brand/taro build:weapp`。直接运行 `taro build` 不会执行遮蔽,产物会带出技术栈指纹;遮蔽后仍检测到指纹时构建会失败。
本地 Admin 默认连接 `http://localhost:3002` 上的统一预览服务。`VITE_TEMPLATE_PREVIEW_URL` 只用于部署时覆盖预览应用地址,不再按模板配置 URL map。
如果希望 API 服务自身也带前缀,可设置 `API_PREFIX=api`。使用 Nginx 去前缀转发时保持默认空值即可,避免重复 `/api/api`。
+1
View File
@@ -39,6 +39,7 @@
`TEMPLATE_KEY=<template-key> API_BASE_URL=<production-api> WEAPP_APP_ID=<appid> pnpm --filter @personal-brand/taro build:weapp`;
- 小程序和 H5 必须分别构建并归档到 `apps/taro/dist/<templateKey>/weapp` 与 `apps/taro/dist/<templateKey>/h5`;产物契约测试通过;
- 产物检查必须覆盖:`project.config.json` 的 AppID、请求内嵌的 `API_BASE_URL`、`/media/` 相对地址补全结果、`common.wxss` 中的按钮规则;
- 产物不得出现 Taro 指纹:`build:weapp`、`build:h5`、`build:preview` 必须走包内脚本(构建后处理失败会中断构建),必要时用 `node config/mask-taro.cjs <weapp|h5> --check` 复核;改名规则只改 `apps/taro/config/mask.config.json`;
- 涉及 `Button`、`Input`、`Textarea`、`Picker` 等原生控件时,源码和产物都要核对;禁止只依据 H5 预览判定小程序样式;
- 按页面角色检查视觉点,不按模板名称写专用清单,并记录截图或说明未改动原因:
- 首页:媒体加载、横向间距、标签换行、整卡点击;