BrowseryTools 是一个开源浏览器工具集：152 个免费工具全部在前端本地运行，文件与文本不上传、无需账号、无广告，覆盖图像处理、PDF、格式转换、计算器与生成器，并支持 17 种语言。想在矩阵中加入一个新工具？核心流程其实只有三步——在工具注册表登记、创建页面、实现组件，再跑一遍校验与测试即可。

为什么新工具"加一次就全都有"

这套项目的架构非常"自动化"：工具清单是唯一的单一数据源。src/lib/tools-config.ts 中的tools数组驱动首页网格、侧边栏、⌘K命令面板搜索、sitemap 与 E2E 测试路由。你在注册表里加一条记录，上述入口就会自动多出一个入口，不需要手动改任何页面。

例如 QR 生成器在注册表中的记录（src/lib/tools-config.ts#L1037-L1046）：

{ name: "QR Code Generator", href: "/tools/qr-generator", icon: QrCodeIcon, available: true, order: 3, creationDate: "2025-08-20", description: "Generate QR codes from text, URLs, contact information, and more.", },

Tool接口的完整字段定义见 src/lib/tools-config.ts#L115-L144。注意一个细节：字段顺序不能乱——generate-tool-routes.mjs脚本用正则解析该文件，name → href → … → available的前缀顺序是它的解析契约，新增可选字段（如landingFor）必须放在creationDate之后。

第一步：在 tools-config.ts 登记新工具

在合适的分类（ToolCategory）的items数组中追加一条记录，需要填齐：

保存后，src/app/sitemap.ts 会自动为新工具生成 URL，无需改动。

第二步：创建工具页面（page.tsx）

每个工具目录包含 3 个文件（参照 src/app/tools/qr-generator/）：

• page.tsx— 页面入口
• opengraph-image.tsx— 社交分享卡片
• twitter-image.tsx— 推特卡片

页面入口非常薄，以 src/app/tools/qr-generator/page.tsx#L1-L8 为例：

import QRCodeGenerator from "@/components/QRCodeGenerator"; import { generateToolMetadata } from "@/lib/metadata"; export const metadata = generateToolMetadata("/tools/qr-generator"); export default function QRGeneratorPage() { return <QRCodeGenerator />; }

generateToolMetadata会读取注册表条目自动生成标题、描述与 hreflang（src/lib/metadata.ts#L5），你只需传入href。OG 卡片同理，一行调用generateToolOgImage("your-tool-slug")即可。

第三步：实现工具组件

组件放在 src/components/ 下，命名YourToolName.tsx。项目已提供大量现成积木，写一个标准工具通常只需几十行：

• src/components/template/tool-shell.tsx — 统一的工具外壳（标题、操作区、SEO 内容区）
• SettingsCard、SliderRow— 参数面板组件
• useTranslations（next-intl）— 组件内文案国际化
• downloadBlob等 src/lib/download.ts — 结果导出

以 src/components/QRCodeGenerator.tsx 为例，它的结构是：状态管理 → 调用第三方库生成结果 → 用ToolShell渲染 → 支持 PNG/SVG 下载。

顺带一提：像 Phone Mockups 这类需要素材的工具，设备边框图已内置在 public/mockup_templates/，新增工具时也可直接把静态资源放进public/目录。

配套内容：SEO 文案与 17 种语言

想让新工具页面拥有完整的内容区块（About、FAQ、HowTo 的 JSON-LD），在 src/lib/tool-content.ts 中以 slug 为键添加条目，参考qr-generator（src/lib/tool-content.ts#L1877）：包含intro、whyClientSide、limitations、faq、steps与related。即使不添加，模板化兜底文案也会保证页面可被收录。

界面文案则需要进入 messages/ 目录：17 个语言文件（en.json、zh-CN.json、ja.json…）中的ToolsConfig.tools.<slug>需要name与description。英文为基准语言，其余语言可后续补译——项目提供prune-orphaned-i18n.mjs脚本清理孤儿词条。

提交前必跑：校验与测试四连

仓库自带严格的守卫，提交前依次执行：

bun run validate # 校验注册表与 README 工具清单是否同步 bun run test # vitest 单元测试（建议为你的组件补一个） bun run e2e:routes # 从 tools-config 重新生成 e2e 路由清单 bun run test:e2e # Playwright 全量冒烟：每条工具路由必须可渲染

几点容易踩的坑：

1. README 必须同步：scripts/validate-tools.js 会比对README.md的工具列表，漏写或分类不匹配都会报错；available: false的工具必须标注(Coming Soon)。
2. 全量冒烟测试：e2e/all-tools-smoke.spec.ts 要求每条路由恰好渲染一个h1且无控制台报错——组件里不要再自造标题。
3. 单元测试参考：src/tests/components/QRCodeGenerator.test.tsx 展示了如何 mock 第三方库并测试交互。
4. 提交钩子：package.json中precommit脚本会自动执行validate + lint，别绕过它。

关键路径速查清单

流程总结：登记 → 建页 → 写组件 → 补文案 → 跑校验。得益于工具矩阵的单一数据源设计，这三步走完后，你的工具会同时出现在首页网格、命令面板搜索、sitemap 和 E2E 冒烟清单中——这正是 BrowseryTools 能把 152 个工具维护得整整齐齐的原因。