企业官网建设流程全解析

• 前端
• 开发工具

本篇技术指南以仓库根目录的 BUILD.md 为核心，系统讲解 Stylus（Userstyles Manager）浏览器扩展的本地构建流程：从 Node.js/PNPM 环境准备、MV2/MV3 多浏览器目标打包、node tools/build.js手动构建参数，到版本发布（pnpm bump）与 Transifex 翻译同步的完整工作流。读完本文，你将能独立搭建构建环境、产出面向 Chrome / Firefox / Chromium 的扩展产物，并理解每条命令背后的 webpack 配置与 manifest 合并实现。

一、环境准备：从零搭建构建工具链

构建 Stylus 扩展需要两个基础工具：Node.js 与 PNPM。

1. 安装 Node.js：访问 Node.js 官网 的engines字段声明"node": ">=24"，因此请确保本机 Node 版本不低于 24，否则依赖安装或构建过程可能报错。
2. 安装 PNPM：PNPM 是该项目指定的包管理器，可通过npm install -g pnpm全局安装，也可按操作系统选择 PNPM 官方安装文档 中的其他方式。仓库的packageManager字段固定为pnpm@12.8.1，建议使用该版本以获得一致的依赖解析行为。
3. 安装依赖：进入项目根目录执行：

pnpm i

该命令会安装全部运行时依赖与开发依赖。此处有两点值得注意：

• preinstall钩子执行npx only-allow pnpm，意味着仓库强制使用 PNPM 而非 npm/yarn，直接用npm install会被拦截；
• postinstall钩子执行node tools/build-cm-css-data.js，它会基于csslint-mod的解析器数据自动再生成 src/cm/css-data.js——这份文件包含 CSS 属性、颜色关键字、伪类、@规则等完整词表，是 CodeMirror 编辑器自动补全的数据源，属于"安装即生成"的产物。

二、准备 Transifex 翻译平台访问

如果只是构建扩展，跳过本节即可；若需要从 Transifex 拉取/推送语言文件（src/_locales/**/messages.json），还需额外两步：

1. 安装 Transifex 客户端，按官方客户端安装指引操作（对应tx命令行工具）；
2. 在项目根目录准备一个.transifexrc文件，其中包含调用 Transifex API 所需的 API Key。该文件通常需要向仓库管理员索取，不要提交到版本库。

这一点与 package.json 中的脚本一一对应：update-locales以tx pull开头、update-transifex以tx push开头，没有tx客户端或.transifexrc时这些命令将无法工作。

三、构建 / 监听：五条命令覆盖全部目标

BUILD.md 提供了标准构建命令表：

这些命令本质都是对node tools/build.js的封装，package.json 的scripts中build-chrome、build-firefox、build-mv2均指向同一入口，区别仅在于npm_lifecycle_event（即执行时的 script 名）不同，tools/util.js正是通过解析该环境变量来区分模式与目标：

• CMD：匹配build|watch|serve，决定 webpack 是run还是watch；
• BUILD：匹配chrome|firefox|any，缺省为any；
• FLAVOR：匹配mv2|mv3，缺省为mv2。

3.1dist目录的清空时机

BUILD.md 特别强调：dist文件夹只在 build（构建）模式下被清空，watch（监听）模式不会清理。对应实现在 tools/webpack.config.js：!DEV时遍历并删除DST目录下的全部文件。这意味着监听模式下你可以在不丢失已有产物的情况下持续叠加增量输出；而正式构建则保证产物目录干净、不含残留旧文件。

3.2 产物目录与版本目标

产物输出目录遵循dist-{目标}-{清单版本}/的命名规则（见 tools/webpack.vars.js）。不同清单对应的浏览器最低版本可在src目录下的 manifest 覆盖文件中确认：

• src/manifest-mv2.json：minimum_chrome_version为 86；
• src/manifest-mv3.json：minimum_chrome_version为 128，MV3 需要 Chrome 128+ 才能使用（涉及declarativeNetRequestWithHostAccess、offscreen、sidePanel等较新 API）；
• src/manifest-mv2-firefox.json：Firefox 的strict_min_version为 68.0，并额外启用sidebar_action侧边栏特性。

构建时，webpack 会合并基础 src/manifest.json 与对应manifest-mv2.json/manifest-mv3.json覆盖文件（makeManifest逻辑见 tools/webpack.config.js），MV3 下还会自动将browser_action重写为action，并按目标浏览器调整 background 入口（MV2 为background.html页面，MV3 为 service workersw.js）。

四、手动执行构建脚本：node tools/build.js全参数说明

除 PNPM 脚本外，BUILD.md 允许直接手动运行node tools/build.js，其参数规则为：

node tools/build.js [build|watch|serve] [any|chrome|firefox] [mv2|mv3]

要点如下：

• 每个参数都是可选的；
• 默认值为build any mv2，即普通构建、目标不限、MV2 清单；
• firefox目标被硬编码为产出 mv2 构建（因为 Firefox 走 MV2 路线）；
• mv3目标被硬编码为产出优化过的 chrome 构建。

这段规则同样可追溯到源码：tools/util.js将第三个参数解析为BUILD、第四个解析为FLAVOR，而 tools/build.js 在入口处做了强校验——MV3 构建仅支持 chrome 目标，若指定mv3搭配firefox或any，会直接以红色错误信息退出（MV3 build is only supported for chrome target），并从 webpack 配置中剔除 Firefox 专属补丁。

此外还可用环境变量微调构建行为（均定义于 tools/webpack.vars.js）：

• FS_CACHE=1：启用 webpack 文件系统缓存，可显著加速重复构建；
• DEBUG=1：开启调试日志（__.DEBUGLOG等宏生效）；
• REPORT=1：生成 webpack-bundle-analyzer 的产物体积分析报告（dist/*.report.html）；
• PROFILE=1：生成 webpack 性能剖析文件。

serve模式（对应HMR）会启动 webpack-dev-server，默认监听localhost:8080，支持热更新与 live-reload，便于在开发浏览器中边改边看。

五、版本发布：打 tag 并自动执行四步流水线

BUILD.md 给出两条版本发布命令：

二者对应 package.json 中的bump: pnpm version patch与bump-stable: pnpm version minor。npm version触发preversion与version两个钩子，从而自动串联起发布流水线：

1. 测试：preversion执行pnpm test，即并行跑 ESLint 代码检查（eslint . --cache）、CSS 解析器回归测试（node tools/test-css.js，用 csslint-mod 校验src/**/*.css）与美化器测试（node --test tools/test-beautify.js，验证 beautify 对:is()、@-moz-document等现代 CSS 语法的处理）；测试不通过则发布中断。
2. 同步版本号：version钩子运行node tools/sync-manifest-version.js并git add .。tools/sync-manifest-version.js 会将 package.json 的版本号写入 src/manifest.json 的version字段，确保扩展清单与包版本始终一致。
3. 生成 ZIP 安装包：发布流程会调用zip脚本（pnpm test && node tools/build-zip.js），产出可直接加载到浏览器或提交商店审阅的压缩包。
4. 推送 tag 到 GitHub：版本号确定后由 git 自动完成 tag 创建与推送。

六、翻译同步：拉取与推送 Transifex 语言文件

Stylus 的界面文案以messages.json形式存放在src/_locales/下，共覆盖 30 多种语言（en、zh_CN、zh_TW、ja、ko、de、fr等），托管在 Transifex 平台上。虽然语言文件全部存在于仓库中，但更新它们必须借助 Transifex 客户端：

从 Transifex 拉取最新翻译：

pnpm update-locales

实际执行的命令链为tx pull --all --minimum-perc=1 && node tools/fix-transifex.js commit（见 package.json）：先以 1% 的完成度门槛拉取全部语言包，再调用 tools/fix-transifex.js 做"净化和提交"。fix-transifex.js的清理规则包括：

• 以英文源文件（en/messages.json）为基准，对键按字母序排序；
• 删除未知键（源文件中不存在的键）与未翻译条目（message缺失或与英文相同）；
• 恢复缺失的placeholders（占位符），避免$1$这类变量在翻译中丢失导致运行时渲染异常；
• 若某语言整个文件为空，则直接删除该语言目录；
• 附加commit参数时，用git commit -m "update locales"自动提交src/_locales/的变更。

将本地文案推送至 Transifex：

pnpm update-transifex

对应tx push -s，仅推送源字符串（source），不会覆盖各语言的翻译进度。

七、构建系统的底层机制：webpack 多配置与浏览器差异化

理解构建命令的差异，核心在于 tools/webpack.config.js 导出的配置数组，它会依据MV3布尔值动态组合配置项：

• 页面入口：edit、manage、options、popup、sidepanel、install-usercss等 HTML 页面均作为独立 webpack entry；MV3 额外增加background/sw（service worker）与offscreen（离屏页面，用于 MV3 下的音频播放等场景）；
• 内容脚本：apply.js、hook-uso.js（userstyles.org 安装钩子）单独打包；MV3 下额外打包hook-uso-page-mv3.js（以MAINworld 注入）；
• 代码分割：CodeMirror、js/color调色板、lz-string压缩库、common公共块等按 cacheGroup 拆分，产物文件名通过getChunkFileName统一清洗（截断超长 chunk 名以兼容 Windows 260 字符路径限制）；
• 第三方库适配：通过makePatchOptions对 less、CodeMirror、csslint-mod、stylus-lang-bundle 等库做字符串级修补（见 tools/wp-patch-less.js、tools/wp-patch-codemirror.js），裁剪浏览器端不需要的模块并注入 CSS 词表数据；
• 代码风格差异：自身代码（isOwn）采用beautify: true的非压缩美化输出，便于用户在 bug 报告里定位行号；vendor 库则走完整压缩路径（terserVendor）。

八、常见问题与排查建议

• MV3 build is only supported for chrome target：说明误用了mv3与其他目标组合，请改用pnpm build-chrome-mv3或手动执行node tools/build.js build chrome mv3。
• Only pnpm is allowed安装报错：仓库通过preinstall的only-allow强制 PNPM，请卸载 npm 安装方式改用pnpm i。
• Node 版本过低：engines要求 Node >= 24，请升级 Node 或使用 nvm 切换。
• tx命令找不到：执行pnpm update-locales/update-transifex前需先安装 Transifex 客户端并配置根目录.transifexrc。
• watch 模式下产物目录越来越乱：这是预期行为（dist只在 build 模式清理），如需干净目录请改用 build 命令。
• 版本号不同步：发布流程依赖version钩子调用tools/sync-manifest-version.js，请勿手动直接修改 src/manifest.json 版本号，以免与package.json脱节。

综上，Stylus 的构建体系以 PNPM + webpack 为底座，通过"PNPM 脚本名 + 手动参数"双入口覆盖 MV2/MV3 与 Chrome/Firefox/通用三种目标，再以npm version钩子把测试、版本同步、ZIP 打包、tag 推送串成一条可复用的发布流水线；翻译则借助 Transifex 客户端与fix-transifex.js的规范化处理保证多语言质量。读者可依据 BUILD.md 与本文逐条复现，从源码产出可用于加载调试或提交商店的扩展包。

• 前端
• 开发工具