Files
persionalBrand/docs/adr/0025-build-output-stack-masking.md
que01 29e5666d74 refactor: 共享按钮尺寸令牌改用中性命名
--taro-button-height / --taro-button-compact-height 是本仓库自有的共享令牌,却借用了
框架名。源码级中性命名比产物替换更彻底,也不会出现源码与产物两套名字,因此改为
--brand-button-height / --brand-button-compact-height,与既有的 brand-button 组件命名一致;
产物遮蔽仍按同一张表处理 Taro 自身的标识符。

验证:weapp 的 app-origin.wxss 输出 page{--brand-button-height:88rpx} 与
button{min-height:var(--brand-button-height)};H5 与后台产物的声明与引用同步改名;
六类产物残留指纹均为 0;H5 预览 11 项浏览器回归通过;遮蔽前后后台产物用生产静态
服务器跑同一套测试,失败内容逐字节一致;format、lint、typecheck 通过。
2026-10-13 23:30:07 +08:00

43 lines
4.6 KiB
Markdown
Raw Permalink 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`、`project.config.json` 的 `projectname` 等。竞争对手据此可以判断预览与小程序都由 Taro 生成。
后台静态站点同样对外可达:Traefik 把 `wechat.app.que01.top` 上除 `/api`、`/media` 以外的全部路径直接转发到 Admin 静态服务器,没有鉴权中间件,因此 `https://…/admin/assets/*.js` 可以直接下载。后台产物里带有模板 renderer 的 glob 路径(`packages/template-*/taro/index.tsx`),同样会暴露技术栈。
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` 做确定性改名;后台静态产物 `apps/admin/dist` 通过 `admin` 目标覆盖,接入根脚本 `build:admin:preview`。
- 同一张替换表同时作用于文件名和文本内容,因此 `taro.js` 与其引用会一起变成 `appkit.js`,`taro_tmpl` 与页面里的引用也保持同步,不需要维护两份映射。
- 只遮蔽 Taro 相关标识符;vite、rollup、rolldown 等通用打包工具的名称属于行业通用信息,不做处理。
- 共享按钮尺寸令牌这类本仓库自有的命名不靠遮蔽处理,而是直接改成中性名:`--taro-button-height` / `--taro-button-compact-height` 改为 `--brand-button-height` / `--brand-button-compact-height`,与既有的 `brand-button` 组件命名保持一致。源码中性命名比产物替换更彻底,也不会让源码与产物出现两套名字。
- 长度 ≥ 40 的不透明串(内嵌 base64、摘要)保持原样,避免误改数据。
- 遮蔽后仍存在 `forbidden` 词表命中时构建失败(退出码 1),因此产物不会静默泄露。
- `project.config.json` 的 `projectname`、`description` 由配置中性化。
- `pnpm deploy:package` 在 `build:admin:preview` 之后对 `apps/admin/dist` 做一次指纹校验,命中即中止打包(`scripts/deploy/package-release.mjs`)。
- 源码与开发构建不改名:`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` 不经过遮蔽。
- 后台静态产物必须通过 `pnpm build:admin:preview`(或 `pnpm deploy:package`)构建;单独运行 `pnpm --filter @personal-brand/admin 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`(后台产物用 `node apps/taro/config/mask-taro.cjs admin --check`);它只检查、不修改。