企业官网建设流程全解析

• 前端
• 浏览器控制

导读

本文基于 STYLE_GUIDE.md 整理，系统讲解 wayback-machine-webextension（Chrome、Firefox、Edge、Safari 14 的 Wayback Machine 浏览器扩展）仓库的代码风格规范：包括 HTML/CSS 与 JavaScript 的缩进、命名、引号、花括号等书写规则，以及如何使用 ESLint 辅助检查格式化与语法问题。读完本文，你将掌握该仓库统一的编码约定，能判断既有代码的偏离点并主动通过重构改进，同时学会借助.eslintrc.json与package.json中的 lint 脚本在提交代码前完成风格校验。

该风格指南并非强制性的完美清单——文中明确说明"部分代码可能尚未遵循本指南，但你可以通过重构帮助改进"，且"某些条目只是建议，可以有例外"，因此把握原则、使用最佳判断是践行本指南的核心姿态。

一、风格指南的定位与适用范围

wayback-machine-webextension 是一个跨浏览器扩展项目，前端代码主体位于 webextension/ 目录，包含 HTML 页面、CSS 样式表与 JavaScript 脚本（如 index.html、css/index.css、scripts/popup.js）。

STYLE_GUIDE.md 面向的就是这一批"Web Extension 代码"。它追求的核心目标包括：

• 一致性：多人协作时，统一的缩进、引号与命名让代码差异最小化，便于 Code Review；
• 可读性：通过hyphen-style类名、lowerCamelCase函数名等约定，让代码意图一目了然；
• 可维护性：鼓励将重复的内联样式抽离到 class 与 CSS 文件中，减少页面膨胀。

指南同时声明了两点弹性原则：一是部分既有代码可能不符合规范，可通过重构逐步纠正；二是部分条目属于建议性质，存在合理例外，应结合具体场景判断。

二、HTML / CSS 规范

2.1 通用书写规则

HTML 与 CSS 的通用规则如下表所示，它们是所有页面与样式文件的基础约定：

以仓库真实代码为例，webextension/css/index.css 中的.tab-bar完全符合"4 空格缩进、左花括号同行、冒号后一个空格"的约定：

.tab-bar { padding-top: 2px; display: flex; justify-content: space-evenly; align-items: center; }

2.2 内联样式与样式复用

指南对内联样式给出两条务实建议：

• 临时可用：HTML 中的内联样式在开发阶段暂时可以接受，但在最终提交前应尽量迁移到.css文件中；
• 优先复用：如果多个#id选择器上重复出现相同样式，应当把这些样式提取到 class 中，而不是复制粘贴。

这一原则与仓库的实际架构一致：所有页面在<head>中引入样式表，例如 webextension/index.html 同时加载了css/bootstrap.css、css/common.css、css/index.css与css/settings.css，业务样式集中管理，而非散落在标签内。

2.3 命名规范

CSS 的 id 与 class 命名遵循：

• 使用hyphen-style（连字符风格）；
• 尽量避免CamelCase与下划线；
• 尽量避免单词类名（single-word classes），两个词的 id 更好，三个词的 id 也可接受。

对照 webextension/css/index.css 中的真实选择器——.tab-bar、.tab-item、.auth-icon-active、.settings-icon-svg——可以看到连字符命名在仓库中的落地情况。

2.4 完整示例

指南给出的 CSS 示例（padding采用2px 0 5px 0的四值写法，兼顾上下与左右留白）：

.tab-bar { padding: 2px 0 5px 0; }

对照真实代码 webextension/css/index.css 中的padding-top: 2px;，两者在缩进与花括号风格上完全一致，仅属性写法因布局需求而异，可见规范在仓库中具有可操作性。

三、JavaScript 规范

3.1 通用书写规则

JavaScript 部分的通用规则如下：

其中"省略分号"与"优先let"这两条在.eslintrc.json中有直接体现：仓库的 ESLint 配置关闭了semi（分号检查）与prefer-const规则，详见下文"ESLint 落地实践"。

3.2 命名规范

JavaScript 命名按作用域分层约定：

• 函数名：lowerCamelCase（小驼峰），如fooBarBaz；
• 类名：UpperCamelCase（大驼峰）；
• 变量名：可以是lowercase、lowerCamelCase或under_scored（下划线风格）；
• 常量：全局或类作用域内的真常量使用CONSTANT_CASE（全大写加下划线）。

指南特别澄清了一个常见误区：JavaScript 中的const语义其实是"一次性赋值"（one-time assignment）而非真正的"不可变常量"，因此只有真正的常量才应转换为全大写命名（例如const PI = 3.14159），其余仅需一次性赋值的变量仍应按普通变量命名，避免滥用全大写风格。

3.3 完整示例

指南给出的 JS 示例：

const FOO = 5 function fooBarBaz(pos) { let fooBar if (pos === FOO) { /* do something */ } else { /* something else */ } }

该示例同时示范了：2 空格缩进、省略分号、if关键字与圆括号之间的空格、K&R 花括号风格、真常量FOO的全大写命名，以及函数名fooBarBaz的小驼峰命名。

四、ESLint 落地实践：从风格指南到自动化检查

4.1 ESLint 的能力边界

STYLE_GUIDE.md 明确指出：ESLint 能捕获一部分基础的格式与语法问题，但并不能覆盖风格指南的全部条目。因此流程上建议"ESLint 检查 + 人工对照指南 Review"双管齐下。具体执行细节记录在 TESTING_GUIDE.md 的Formatting & Style一节。

4.2 仓库中的 ESLint 配置

仓库根目录的 .eslintrc.json 是风格落地的关键依据：

• extends: "standard"：基于 JavaScript Standard Style 预设规则；
• env：启用browser、webextensions、worker三套环境，以识别浏览器扩展特有的全局对象；
• 定制规则：indent设定为 2 空格（warn级别，并允许SwitchCase缩进 1 级、MemberExpression不强制缩进）；同时关闭了brace-style、camelcase、space-before-function-paren、prefer-const、quote-props、one-var、padded-blocks、dot-notation、semi等规则；
• globals：将 jQuery 的$声明为只读全局变量，避免在脚本中出现no-undef误报。

这套配置与风格指南中的"省略分号、优先let、K&R 花括号"等约定互相呼应：规则文件中显式放开了这些项的约束。

此外，样式侧还配置了 .stylelintrc.yml，直接继承stylelint-config-standard，用于对 webextension/css 目录下的 CSS 文件做风格检查。

4.3 安装与运行

测试与 lint 环境依赖npm install安装。从 package.json 可以看到仓库预置了三个 lint 脚本：

"lint": "npm run lint:js && npm run lint:css", "lint:js": "eslint webextension/scripts test", "lint:css": "stylelint webextension/css"

• 一次性执行全部检查：npm run lint；
• 单独检查 JavaScript（覆盖 webextension/scripts 与 test/ 目录）：npm run lint:js；
• 单独检查 CSS（覆盖 webextension/css 目录）：npm run lint:css。

更细粒度的运行方式（见 TESTING_GUIDE.md）：

• 查看 ESLint 选项：npx eslint（调用node_modules/.bin/下的本地版本；若系统中全局安装了 ESLint，也可省略npx）；
• 检查单个文件：npx eslint webextension/scripts/example.js；
• 建议不要直接使用--fix选项，而是先手动修复问题，以加深对规则的理解。

4.4 外部全局变量的注释声明

为避免no-undef误报，应在脚本顶部以注释形式声明外部全局变量。这一约定在仓库源码中有大量实例，例如 webextension/scripts/popup.js：

// popup.js // from 'utils.js' /* global isArchiveUrl, isValidUrl, makeValidURL, isNotExcludedUrl, getCleanUrl, openByWindowSetting, hostURL */ /* global feedbackURL, newshosts, dateToTimestamp, timestampToDate, viewableTimestamp, fixedEncodeURIComponent */ /* global attachTooltip, checkLastError, cropPrefix, cropScheme, hostHeaders, getUserInfo, checkAuthentication */

同样地，webextension/scripts/utils.js 顶部也通过/* global isInTestEnv */声明测试环境变量，webextension/scripts/about.js 则声明了feedbackURL, newshosts。新增脚本时照此模式声明外部依赖，即可与仓库的 ESLint 配置无缝配合。

五、从指南到构建：风格约定在仓库中的印证

5.1 缩进与命名在源码中的落地

以真实文件验证指南的可行性：

• HTML 2 空格缩进：参见 webextension/index.html 的页面结构，标签层级均以 2 空格递进；
• CSS 4 空格缩进 + 连字符命名：参见 webextension/css/index.css 与 webextension/css/settings.css（如#setting-page、.setting-switch）；
• JS 2 空格缩进 + 小驼峰函数：参见 webextension/scripts/utils.js 中的getBrowser()、fixedEncodeURIComponent()等函数定义。

5.2 构建产物与风格的关系

值得注意的是，TESTING_GUIDE.md 中提到项目已不再生成压缩的build.js，而是直接使用可读、非压缩的 JavaScript 源码，以通过 Firefox 的代码审查要求；jQuery、Bootstrap 等库统一放置在 webextension/libs 目录。仓库仍保留 webpack.config.js 用于构建场景（入口为 webextension/scripts/index.js，输出webextension/scripts/build.js），但主扩展代码始终强调可读性——这与本风格指南"为可读性服务"的目标一脉相承。

5.3 配合测试与提交流程

风格检查应纳入日常开发闭环。按 CONTRIBUTING.md 的推荐实践，为example.js编写测试时应新建test/example.spec.js，提交前运行npm test并对照 TESTING_GUIDE.md 完成自动化与手动测试。风格检查（npm run lint）与功能测试（npm test，基于 Mocha）共同构成提交前的质量闸门。

六、总结：如何践行这份风格指南

1. 新代码严格遵守：缩进（HTML 2 空格 / CSS 4 空格 / JS 2 空格，均不用 Tab）、命名（CSS 连字符、JS 小驼峰函数与大驼峰类）、引号（HTML 双引号、CSS 与 JS 单引号）、分号（JS 省略）等硬性约定应内化为书写习惯；
2. 旧代码渐进重构：指南明确指出部分代码尚未符合规范，遇到即可顺手改进，例如把重复的#id样式提取为 class、把内联样式迁移到 CSS 文件；
3. 自动化兜底：修改代码后运行npx eslint webextension/scripts/example.js捕获基础问题，再人工对照 STYLE_GUIDE.md 与 TESTING_GUIDE.md 复核；
4. 允许合理例外：个别条目仅是建议，在上下文更合适时使用最佳判断，不必机械教条。

遵循这份风格指南，不仅能让你的 PR 更容易通过 review，也能让 wayback-machine-webextension 这个跨浏览器扩展项目在长期演进中保持统一、可读、易维护的代码基座。

• 前端
• 浏览器控制