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:
1 parent
53713e5935
commit
9ad2776515
13 files changed
+382
-10
No files matched your search
@@ -35,6 +35,16 @@ TEMPLATE_KEY=linjing-editorial pnpm --filter @personal-brand/taro build:weapp
|
||||
|
||||
页面结构和样式以 React 原型为参考,当前原生小程序用于校对字段、结构化来源、认证与提交行为。模板实现位于各 package 的 `taro/`;公共请求、表单、记录和状态位于此目录。新模板须提供 manifest、Taro 实现和验收用例,不新增全局 seed。
|
||||
|
||||
## 构建产物遮蔽
|
||||
|
||||
生产构建会调用构建后处理脚本 `config/mask-taro.cjs`,按 `config/mask.config.json` 替换产物里的 Taro 标识符(文件名与内容使用同一张表),遮蔽后仍命中 `forbidden` 词表时构建失败。`build:h5`、`build:weapp`、`build:preview` 都已接入;`dev:h5`、`dev:preview` 保持原始命名便于调试。改架构名只改 `config/mask.config.json`;复核某次产物是否干净用:
|
||||
|
||||
```sh
|
||||
TEMPLATE_KEY=acheng-campus-food node config/mask-taro.cjs weapp --check
|
||||
```
|
||||
|
||||
由于产物名称与源码名称不同,产物契约测试用 `test/mask-names.mjs` 的 `unmask()` 还原后再断言,浏览器测试的选择器写成 `:is(<源码名>, <遮蔽名>)`。机制与取舍见 [docs/adr/0025-build-output-stack-masking.md](../../docs/adr/0025-build-output-stack-masking.md)。
|
||||
|
||||
## 使用边界
|
||||
|
||||
Web 支持真实已发布内容、导航、餐品搜索/分类、咨询表单填写和校验。未接入 Web 身份登录,因此没有微信会话时不会提交,不生成假咨询或伪造成功。微信小程序采用 Taro.login 和原 customer/session/wechat 接口。令牌按品牌隔离;请求失败保留表单输入,401 清理会话。
|
||||
|
||||
@@ -29,7 +29,7 @@ fs.cpSync(path.join(template, "miniapp/assets"), path.resolve(__dirname, "../src
|
||||
recursive: true,
|
||||
});
|
||||
export default defineConfig({
|
||||
projectName: "personal-brand-taro",
|
||||
projectName: "personal-brand-miniapp",
|
||||
date: "2026-10-08",
|
||||
designWidth: 750,
|
||||
deviceRatio: { 750: 1 },
|
||||
|
||||
@@ -0,0 +1,197 @@
|
||||
/**
|
||||
* 构建后处理:把产物里的 Taro 指纹替换成中性标识。
|
||||
*
|
||||
* 同一张替换表同时作用于「文件名」和「文本内容」,因此 taro.js 会连文件名带引用
|
||||
* 一起变成 appkit.js,模板名 taro_tmpl 与页面里的引用也会同步,无需分别维护。
|
||||
*
|
||||
* 用法:
|
||||
* node config/mask-taro.cjs weapp 处理后 dist/<template>/weapp
|
||||
* node config/mask-taro.cjs h5 处理后 dist/<template>/h5
|
||||
* node config/mask-taro.cjs h5 --preview 处理后 dist/template-preview/h5
|
||||
* node config/mask-taro.cjs weapp --check 只检查是否仍有指纹,不修改
|
||||
*/
|
||||
const fs = require("node:fs");
|
||||
const path = require("node:path");
|
||||
|
||||
const taroRoot = path.resolve(__dirname, "..");
|
||||
const configPath = path.join(__dirname, "mask.config.json");
|
||||
|
||||
/** 需要做文本替换的扩展名,二进制文件一律跳过。 */
|
||||
const textExtensions = new Set([
|
||||
".js",
|
||||
".mjs",
|
||||
".cjs",
|
||||
".json",
|
||||
".wxml",
|
||||
".wxss",
|
||||
".wxs",
|
||||
".css",
|
||||
".html",
|
||||
]);
|
||||
|
||||
function loadConfig() {
|
||||
return JSON.parse(fs.readFileSync(configPath, "utf8"));
|
||||
}
|
||||
|
||||
/** 长键优先,避免 `@tarojs` 被 `taro` 抢先替换成 `@appkitjs` 这种半成品。 */
|
||||
function orderedReplacements(replacements) {
|
||||
return Object.entries(replacements ?? {}).sort(([a], [b]) => b.length - a.length);
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
||||
}
|
||||
|
||||
/** 连续的长 base64/哈希片段:可能是内嵌图片、密钥或摘要,替换进去会损坏数据。 */
|
||||
const opaqueRun = /[A-Za-z0-9+/=]{40,}/;
|
||||
const opaqueRunSplit = /([A-Za-z0-9+/=]{40,})/;
|
||||
|
||||
/**
|
||||
* 把内容切成「可替换区段」和「受保护区段」,只在前者做替换。
|
||||
* 这样既能命中边界处的 `taro_tmpl`,也能命中 camelCase 的 `modifyTaroEvent`,
|
||||
* 又不会动到内嵌的 base64 数据。
|
||||
*/
|
||||
function maskText(content, replacements) {
|
||||
const entries = orderedReplacements(replacements);
|
||||
return content
|
||||
.split(opaqueRunSplit)
|
||||
.map((segment) =>
|
||||
opaqueRun.test(segment)
|
||||
? segment
|
||||
: entries.reduce(
|
||||
(result, [from, to]) => result.replace(new RegExp(escapeRegExp(from), "g"), to),
|
||||
segment,
|
||||
),
|
||||
)
|
||||
.join("");
|
||||
}
|
||||
|
||||
function maskFileName(name, replacements) {
|
||||
return orderedReplacements(replacements).reduce(
|
||||
(result, [from, to]) => result.replace(new RegExp(escapeRegExp(from), "g"), to),
|
||||
name,
|
||||
);
|
||||
}
|
||||
|
||||
function resolveTargets(envType, preview) {
|
||||
if (preview) return [path.join(taroRoot, "dist/template-preview/h5")];
|
||||
const templateKey = process.env.TEMPLATE_KEY;
|
||||
if (!templateKey) throw new Error("TEMPLATE_KEY is required for non-preview masking");
|
||||
return [path.join(taroRoot, "dist", templateKey, envType)];
|
||||
}
|
||||
|
||||
function walk(directory) {
|
||||
const files = [];
|
||||
for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
|
||||
const full = path.join(directory, entry.name);
|
||||
if (entry.isDirectory()) files.push(...walk(full));
|
||||
else if (entry.isFile()) files.push(full);
|
||||
}
|
||||
return files;
|
||||
}
|
||||
|
||||
function maskProjectConfig(directory, config) {
|
||||
const target = path.join(directory, "project.config.json");
|
||||
if (!fs.existsSync(target)) return;
|
||||
const current = JSON.parse(fs.readFileSync(target, "utf8"));
|
||||
const next = { ...current, ...(config.project ?? {}) };
|
||||
fs.writeFileSync(target, `${JSON.stringify(next, null, 2)}\n`);
|
||||
}
|
||||
|
||||
function renameFiles(directory, files, replacements) {
|
||||
const renamed = [];
|
||||
for (const file of files) {
|
||||
const currentName = path.basename(file);
|
||||
const nextName = maskFileName(currentName, replacements);
|
||||
if (nextName === currentName) continue;
|
||||
const next = path.join(path.dirname(file), nextName);
|
||||
if (fs.existsSync(next)) throw new Error(`遮蔽后文件名冲突:${next}`);
|
||||
fs.renameSync(file, next);
|
||||
renamed.push([currentName, nextName]);
|
||||
}
|
||||
return renamed;
|
||||
}
|
||||
|
||||
function maskDirectory(directory, config, { check = false } = {}) {
|
||||
if (!fs.existsSync(directory)) throw new Error(`产物目录不存在:${directory}`);
|
||||
const replacements = config.replacements ?? {};
|
||||
const files = walk(directory);
|
||||
let rewritten = 0;
|
||||
|
||||
for (const file of files) {
|
||||
if (!textExtensions.has(path.extname(file))) continue;
|
||||
const content = fs.readFileSync(file, "utf8");
|
||||
const masked = maskText(content, replacements);
|
||||
if (masked === content) continue;
|
||||
rewritten += 1;
|
||||
if (!check) fs.writeFileSync(file, masked);
|
||||
}
|
||||
|
||||
const renamed = check ? [] : renameFiles(directory, files, replacements);
|
||||
if (!check) maskProjectConfig(directory, config);
|
||||
|
||||
return {
|
||||
directory,
|
||||
scanned: files.length,
|
||||
rewritten,
|
||||
renamed,
|
||||
leaked: findLeaks(directory, config),
|
||||
};
|
||||
}
|
||||
|
||||
/** 扫描整个产物目录,返回仍然含有指纹的位置,用于守卫。 */
|
||||
function findLeaks(directory, config) {
|
||||
const forbidden = config.forbidden ?? [];
|
||||
if (!forbidden.length) return [];
|
||||
const leaks = [];
|
||||
for (const file of walk(directory)) {
|
||||
const name = path.basename(file);
|
||||
if (forbidden.some((token) => name.includes(token))) {
|
||||
leaks.push(`${path.relative(directory, file)} :: 文件名`);
|
||||
continue;
|
||||
}
|
||||
if (!textExtensions.has(path.extname(file))) continue;
|
||||
const content = fs.readFileSync(file, "utf8");
|
||||
for (const token of forbidden) {
|
||||
if (content.includes(token)) {
|
||||
leaks.push(`${path.relative(directory, file)} :: 内容包含 ${token}`);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
return leaks;
|
||||
}
|
||||
|
||||
function main() {
|
||||
const args = process.argv.slice(2);
|
||||
const envType = args.find((arg) => !arg.startsWith("--")) ?? "weapp";
|
||||
const preview = args.includes("--preview");
|
||||
const check = args.includes("--check");
|
||||
const config = loadConfig();
|
||||
|
||||
if (!config.enabled && !check) {
|
||||
console.log("[mask] 配置为 enabled: false,跳过遮蔽");
|
||||
return;
|
||||
}
|
||||
|
||||
let failed = false;
|
||||
for (const directory of resolveTargets(envType, preview)) {
|
||||
const result = maskDirectory(directory, config, { check });
|
||||
const relative = path.relative(taroRoot, result.directory);
|
||||
console.log(
|
||||
`[mask] ${relative}:扫描 ${result.scanned} 个文件,改写 ${result.rewritten} 个` +
|
||||
(result.renamed.length ? `,重命名 ${result.renamed.length} 个` : ""),
|
||||
);
|
||||
for (const [from, to] of result.renamed) console.log(`[mask] 重命名 ${from} -> ${to}`);
|
||||
if (result.leaked.length) {
|
||||
failed = true;
|
||||
console.error(`[mask] ${relative} 仍存在技术栈指纹:`);
|
||||
for (const leak of result.leaked.slice(0, 20)) console.error(` - ${leak}`);
|
||||
}
|
||||
}
|
||||
if (failed) process.exit(1);
|
||||
}
|
||||
|
||||
module.exports = { maskText, maskFileName, maskDirectory, findLeaks, loadConfig };
|
||||
|
||||
if (require.main === module) main();
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"enabled": true,
|
||||
"replacements": {
|
||||
"@tarojs": "@app-kit",
|
||||
"taro": "appkit",
|
||||
"Taro": "AppKit",
|
||||
"TARO": "APPKIT"
|
||||
},
|
||||
"project": {
|
||||
"projectname": "personal-brand-miniapp",
|
||||
"description": "个人品牌小程序发布产物"
|
||||
},
|
||||
"forbidden": ["taro", "Taro", "TARO", "tarojs", "@tarojs"]
|
||||
}
|
||||
@@ -4,9 +4,9 @@
|
||||
"scripts": {
|
||||
"dev:h5": "taro build --type h5 --watch",
|
||||
"dev:preview": "PREVIEW_ALL_TEMPLATES=true taro build --type h5 --watch",
|
||||
"build:h5": "taro build --type h5",
|
||||
"build:preview": "PREVIEW_ALL_TEMPLATES=true taro build --type h5",
|
||||
"build:weapp": "taro build --type weapp",
|
||||
"build:h5": "taro build --type h5 && node config/mask-taro.cjs h5",
|
||||
"build:preview": "PREVIEW_ALL_TEMPLATES=true taro build --type h5 && node config/mask-taro.cjs h5 --preview",
|
||||
"build:weapp": "taro build --type weapp && node config/mask-taro.cjs weapp",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"lint": "pnpm --workspace-root exec eslint apps/taro/src apps/taro/config \"packages/template-*/taro/**/*.{ts,tsx}\"",
|
||||
"test": "node --experimental-strip-types --test test/*.test.mjs",
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
import { test, expect } from "@playwright/test";
|
||||
|
||||
// 产物会遮蔽 Taro 运行时命名,选择器同时接受源码名称与遮蔽名称。
|
||||
const BUTTON_CORE = ":is(taro-button-core, appkit-button-core)";
|
||||
const TABBAR = ":is(.taro-tabbar__tabbar, .appkit-tabbar__tabbar)";
|
||||
test("真实 API 驱动首页、出摊和主理人视觉槽位", async ({ page }) => {
|
||||
const errors: string[] = [];
|
||||
page.on("pageerror", (error) => errors.push(error.message));
|
||||
@@ -57,7 +61,7 @@ test("餐品搜索、详情和咨询目标传递", async ({ page }) => {
|
||||
const name = await page.locator(".dish-name").first().textContent();
|
||||
await page.locator(".offering-card").first().click();
|
||||
await expect(page.locator(".hero-copy")).toContainText(name!);
|
||||
await page.locator(".bar taro-button-core").click();
|
||||
await page.locator(`.bar ${BUTTON_CORE}`).click();
|
||||
await expect(page.locator(".inquiry-form")).toBeVisible();
|
||||
await expect(page.locator(".half-field")).toHaveCount(4);
|
||||
});
|
||||
@@ -124,17 +128,17 @@ for (const width of [375, 430, 768, 1280]) {
|
||||
await page.goto("/");
|
||||
await expect(page.locator(".food-home .name")).toBeVisible();
|
||||
const expectedWidth = Math.min(width, 430);
|
||||
const bounds = await page.evaluate(() => {
|
||||
const bounds = await page.evaluate((tabSelector) => {
|
||||
const rect = (selector: string) => {
|
||||
const box = document.querySelector(selector)!.getBoundingClientRect();
|
||||
return { width: box.width, left: box.left };
|
||||
};
|
||||
return {
|
||||
page: rect(".food-home .page"),
|
||||
tab: rect(".taro-tabbar__tabbar"),
|
||||
tab: rect(tabSelector),
|
||||
overflow: document.documentElement.scrollWidth > window.innerWidth,
|
||||
};
|
||||
});
|
||||
}, TABBAR);
|
||||
expect(bounds.page.width).toBeCloseTo(expectedWidth, 0);
|
||||
expect(bounds.tab.width).toBeCloseTo(expectedWidth, 0);
|
||||
expect(bounds.tab.left).toBeCloseTo(bounds.page.left, 0);
|
||||
@@ -167,7 +171,7 @@ for (const width of [375, 1280]) {
|
||||
};
|
||||
const aboveNavigation = async (selector: string) => {
|
||||
const bottom = await page.locator(selector).last().boundingBox();
|
||||
const nav = await page.locator(".taro-tabbar__tabbar").boundingBox();
|
||||
const nav = await page.locator(TABBAR).boundingBox();
|
||||
expect(bottom!.y + bottom!.height).toBeLessThan(nav!.y - 8);
|
||||
};
|
||||
await page.goto("/");
|
||||
|
||||
@@ -2,6 +2,7 @@ import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { unmask } from "./mask-names.mjs";
|
||||
const root = path.resolve(import.meta.dirname, "../../..");
|
||||
const templateKeys = fs
|
||||
.readdirSync(path.join(root, "packages"))
|
||||
@@ -31,7 +32,7 @@ for (const key of templateKeys)
|
||||
);
|
||||
assert.ok(fs.existsSync(path.join(base, "weapp/project.config.json")));
|
||||
const weappStyles = fs.readFileSync(path.join(base, "weapp/common.wxss"), "utf8");
|
||||
const appStyles = fs.readFileSync(path.join(base, "weapp/app-origin.wxss"), "utf8");
|
||||
const appStyles = unmask(fs.readFileSync(path.join(base, "weapp/app-origin.wxss"), "utf8"));
|
||||
assert.ok(weappStyles.length > 1000);
|
||||
assert.match(appStyles, /(^|})button\{/);
|
||||
assert.match(appStyles, /--taro-button-height:\s*88rpx/);
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
|
||||
const configPath = path.join(import.meta.dirname, "../config/mask.config.json");
|
||||
export const maskConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
|
||||
|
||||
const entries = Object.entries(maskConfig.replacements).sort(([a], [b]) => b.length - a.length);
|
||||
const reverseEntries = entries
|
||||
.map(([from, to]) => [to, from])
|
||||
.sort(([a], [b]) => b.length - a.length);
|
||||
|
||||
/** 按遮蔽配置推导名称,测试与构建共用同一张表,避免两边写死而不同步。 */
|
||||
export function masked(name) {
|
||||
if (!maskConfig.enabled) return name;
|
||||
return entries.reduce((result, [from, to]) => result.split(from).join(to), name);
|
||||
}
|
||||
|
||||
/** 把制品中的名称还原成源码名称,让产物契约断言不依赖产物是否已经遮蔽。 */
|
||||
export function unmask(name) {
|
||||
if (!maskConfig.enabled) return name;
|
||||
return reverseEntries.reduce((result, [from, to]) => result.split(from).join(to), name);
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import fs from "node:fs";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import { createRequire } from "node:module";
|
||||
import { maskConfig, masked, unmask } from "./mask-names.mjs";
|
||||
|
||||
const require = createRequire(import.meta.url);
|
||||
const { maskText, maskFileName, maskDirectory, findLeaks } = require("../config/mask-taro.cjs");
|
||||
|
||||
const replacements = maskConfig.replacements;
|
||||
/** 长度超过 40 的 base64/哈希片段,遮蔽时必须原样保留。 */
|
||||
const opaqueRun = `QWxhZGRpbjpvcGVuIHNlc2FtZQ${"taro"}VzYW1lQW5kUGFzc3dvcmQ`;
|
||||
|
||||
test("遮蔽表在测试与构建之间保持一致", () => {
|
||||
for (const name of [
|
||||
"taro-button-core",
|
||||
"taro_tmpl",
|
||||
"@tarojs/components",
|
||||
"taroWindowProvider",
|
||||
"--taro-button-height",
|
||||
".taro-tabbar__tabbar",
|
||||
])
|
||||
assert.equal(masked(name), maskText(name, replacements), name);
|
||||
assert.equal(masked("taro-button-core"), "appkit-button-core");
|
||||
assert.equal(masked(".taro-tabbar__tabbar"), ".appkit-tabbar__tabbar");
|
||||
assert.deepEqual(
|
||||
Object.keys(replacements).map((from) => unmask(masked(from))),
|
||||
Object.keys(replacements),
|
||||
);
|
||||
});
|
||||
|
||||
test("文本遮蔽改标识符但不损坏不透明数据段", () => {
|
||||
const content = `var tmpl="taro_tmpl";var key="${opaqueRun}";const modifyTaroEvent=1;`;
|
||||
const result = maskText(content, replacements);
|
||||
assert.ok(result.includes('"appkit_tmpl"'));
|
||||
assert.ok(result.includes(`"${opaqueRun}"`));
|
||||
assert.ok(result.includes("modifyAppKitEvent"), "camelCase 标识符必须一起遮蔽");
|
||||
assert.ok(!/taro/i.test(result.replace(opaqueRun, "")), "可替换区段不得残留指纹");
|
||||
});
|
||||
|
||||
test("文件名遮蔽与内容使用同一张表", () => {
|
||||
assert.equal(maskFileName("taro.js", replacements), "appkit.js");
|
||||
assert.equal(maskFileName("taro-tmpl.wxml", replacements), "appkit-tmpl.wxml");
|
||||
assert.equal(maskFileName("common.wxss", replacements), "common.wxss");
|
||||
});
|
||||
|
||||
test("遮蔽产物目录:文件名、引用与 project.config.json 同步更新且无残留指纹", () => {
|
||||
const directory = fs.mkdtempSync(path.join(os.tmpdir(), "mask-taro-"));
|
||||
try {
|
||||
fs.mkdirSync(path.join(directory, "assets"));
|
||||
const binary = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00, 0xff]);
|
||||
fs.writeFileSync(path.join(directory, "assets/logo.png"), binary);
|
||||
fs.writeFileSync(path.join(directory, "app.js"), 'require("./taro.js");\n');
|
||||
fs.writeFileSync(path.join(directory, "taro.js"), 'var tmpl="taro_tmpl";\n');
|
||||
fs.writeFileSync(path.join(directory, "taro-tmpl.wxml"), '<template name="taro_tmpl"/>\n');
|
||||
fs.writeFileSync(
|
||||
path.join(directory, "project.config.json"),
|
||||
`${JSON.stringify({ appid: "wx-test", projectname: "personal-brand-taro" }, null, 2)}\n`,
|
||||
);
|
||||
|
||||
const result = maskDirectory(directory, maskConfig);
|
||||
|
||||
assert.deepEqual(result.leaked, []);
|
||||
assert.deepEqual(findLeaks(directory, maskConfig), []);
|
||||
assert.ok(fs.existsSync(path.join(directory, "appkit.js")), "被引用的文件必须同步改名");
|
||||
assert.ok(fs.existsSync(path.join(directory, "appkit-tmpl.wxml")));
|
||||
assert.equal(
|
||||
fs.readFileSync(path.join(directory, "app.js"), "utf8"),
|
||||
'require("./appkit.js");\n',
|
||||
);
|
||||
assert.equal(fs.existsSync(path.join(directory, "taro.js")), false, "旧文件名不能残留");
|
||||
const projectConfig = JSON.parse(
|
||||
fs.readFileSync(path.join(directory, "project.config.json"), "utf8"),
|
||||
);
|
||||
assert.equal(projectConfig.projectname, maskConfig.project.projectname);
|
||||
assert.equal(projectConfig.appid, "wx-test");
|
||||
assert.deepEqual(fs.readFileSync(path.join(directory, "assets/logo.png")), binary);
|
||||
} finally {
|
||||
fs.rmSync(directory, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
@@ -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`;它只检查、不修改。
|
||||
@@ -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`。
|
||||
|
||||
@@ -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 预览判定小程序样式;
|
||||
- 按页面角色检查视觉点,不按模板名称写专用清单,并记录截图或说明未改动原因:
|
||||
- 首页:媒体加载、横向间距、标签换行、整卡点击;
|
||||
|
||||
@@ -16,6 +16,7 @@ export default tseslint.config(
|
||||
"packages/types/test/**/*.test.mjs",
|
||||
"apps/taro/test/**/*.test.mjs",
|
||||
"apps/taro/src/assets/**",
|
||||
"apps/taro/config/**/*.cjs",
|
||||
"apps/miniapp/pages/**/*.js",
|
||||
"apps/miniapp/app.js",
|
||||
"apps/admin/vite.config.ts",
|
||||
|
||||
Reference in new issue
Block a user