Excalidraw代码规范：ESLint/Prettier统一风格

Excalidraw 代码规范实践：用 ESLint 与 Prettier 构建协作一致性

在开源项目中，最让人头疼的往往不是复杂的功能逻辑，而是那些看似微不足道却频繁发生的“风格之争”——单引号还是双引号？分号要不要加？缩进用两个空格还是四个？当来自世界各地的开发者共同维护一个项目时，这些细节很容易演变成 PR 中无休止的评论和反复修改。

Excalidraw 正是这样一个典型的例子。作为一款以极简美学著称的在线手绘风白板工具，它不仅追求视觉上的干净利落，在工程实现上也力求清晰、一致。为了支撑多人协作下的高质量交付，项目团队选择了 ESLint 和 Prettier 这对黄金组合，将代码规范从“人为约定”转变为“自动执行”。

这套机制背后并不仅仅是几行配置文件那么简单，而是一整套贯穿开发、提交到集成全流程的工程化设计。它让每个贡献者都能写出风格统一的代码，也让审查者可以专注于真正重要的问题：逻辑是否合理、架构是否健壮。

为什么是 ESLint？

ESLint 的核心价值在于静态分析能力。它不运行代码，而是通过解析源码生成抽象语法树（AST），逐节点检查是否存在潜在问题。这种机制使得它不仅能捕捉语法错误，还能识别出诸如未使用变量、不安全的类型操作、违反最佳实践等深层次问题。

在 Excalidraw 中，由于主体采用 TypeScript 编写，并大量使用 React 和 JSX，因此其 ESLint 配置特别依赖插件体系来扩展支持：

module.exports = { root: true, env: { browser: true, es2021: true, node: true, }, extends: [ 'eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:react/recommended', 'plugin:jsx-a11y/recommended', ], parser: '@typescript-eslint/parser', parserOptions: { ecmaFeatures: { jsx: true, }, ecmaVersion: 'latest', sourceType: 'module', }, plugins: ['@typescript-eslint', 'react', 'jsx-a11y'], settings: { react: { version: 'detect', }, }, rules: { '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }], 'no-console': 'warn', 'react/react-in-jsx-scope': 'off', }, };

这个.eslintrc.cjs文件虽然看起来结构规整，但每一项都有明确的设计意图。

比如@typescript-eslint/parser是关键所在——没有它，ESLint 根本无法理解 TypeScript 的类型注解；而'plugin:react/recommended'则启用了针对 React 的专门规则，如防止直接修改 props 或遗漏 key 属性。至于'jsx-a11y/recommended'，则是为了确保界面具备基本的可访问性，比如按钮有正确的 role 和 label。

有意思的是，'react/react-in-jsx-scope'被手动关闭了。这并不是疏忽，而是因为 Excalidraw 使用的是 React 17+ 版本，该版本引入了新的 JSX 转换机制，不再需要显式导入React即可使用 JSX 语法。如果保留这条规则，反而会导致误报。

再看自定义规则：

'@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }]

这一条非常实用。TypeScript 开发中常会遇到某些参数必须声明但暂时不用的情况（例如事件回调中的event）。如果不处理，ESLint 会报错。而通过正则^_忽略以下划线开头的参数名，既保留了警告的有效性，又避免了为“绕过检查”而去注释掉规则的坏习惯。

还有no-console: 'warn'——选择警告而非错误，体现了团队的务实态度。调试阶段打印日志是刚需，完全禁止会影响效率；但也不鼓励上线时保留 console 输出，所以用 warn 提醒即可。

Prettier：终结格式战争的利器

如果说 ESLint 是“守门员”，负责守住代码质量底线，那 Prettier 就更像是“美容师”——它不管你的逻辑对不对，只关心代码看起来漂不漂亮。

它的哲学很极端：格式问题不该有争论，工具说了算。

Prettier 的工作方式也与此匹配：它不会尝试局部调整，而是把整个文件重新排版。无论你原本怎么写，只要交给 Prettier，输出的结果都是一样的。这就彻底杜绝了“我看着舒服就行”的主观判断。

来看 Excalidraw 的.prettierrc.json：

{ "semi": false, "singleQuote": true, "tabWidth": 2, "trailingComma": "es5", "printWidth": 80, "arrowParens": "avoid" }

这套配置透露出明显的现代 JavaScript 审美倾向：

• 不要分号（semi: false）——这是受 ASI（自动分号插入）机制影响的一种流行风格，也被许多主流项目（如 Vue）采纳；
• 单引号优先（singleQuote: true）——减少键盘切换成本，同时与 JSON 兼容更好；
• 两空格缩进（tabWidth: 2）——比四空格更紧凑，适合嵌套较深的 JSX 结构；
• 尾随逗号（trailingComma: "es5"）——在对象或数组最后一项后加逗号，Git diff 更友好，增删元素时不连带修改相邻行；
• 80 字符换行（printWidth: 80）——兼顾终端显示和现代屏幕宽度，避免一行过长影响阅读；
• 箭头函数省略括号（arrowParens: "avoid"）——单参数时不加括号，更简洁，如x => x * 2。

这些设置本身并不复杂，但真正聪明的地方在于它与 ESLint 的协同方式。

很多人初用这两者时容易踩坑：ESLint 想要强制分号，Prettier 却自动去掉；ESLint 检查缩进为空格，Prettier 却按 tab 处理……结果就是互相打架。

Excalidraw 的解决方案非常标准但也极为有效：在extends数组末尾加上'prettier'：

extends: [ 'eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:react/recommended', 'prettier' // 放在最后！ ]

这个'prettier'来自eslint-config-prettier包，作用是关闭所有与格式相关的 ESLint 规则。这样一来，ESLint 只管逻辑层面的问题（比如变量未定义、类型错误），而所有关于“怎么排版”的决策全部交给 Prettier 处理。

顺序也很关键——必须放在extends最后，才能正确覆盖前面可能激活的格式规则。

工程落地：从本地开发到 CI 防线

再好的工具，如果不能无缝融入工作流，最终也会被束之高阁。Excalidraw 的高明之处在于，它构建了一条从编辑器到 CI 的完整防护链，让规范执行变得“无感但可靠”。

整个流程大致如下：

[开发者编写代码] ↓ [VSCode + 插件] → 保存即格式化 & 实时提示 ↓ [Git Hook (Husky + lint-staged)] → 提交前自动修复 ↓ [CI Pipeline (GitHub Actions)] → 全量检查，失败则阻断合并 ↓ [Merged PR → 构建发布]

第一道防线：编辑器即时反馈

几乎所有 Excalidraw 贡献者都在使用 VSCode，项目也贴心地提供了推荐插件列表（.vscode/extensions.json），其中就包括：

• ESLint
• Prettier - Code formatter

一旦安装，开发者每次保存.ts/.tsx/.js文件时，Prettier 会自动重排格式，ESLint 则实时标出潜在问题（红色波浪线）。这种即时反馈极大降低了犯错成本，甚至很多人根本意识不到自己“被纠正”了。

更重要的是，这种自动化减少了新成员的学习负担。他们不需要死记硬背“本项目用单引号、不加分号”，只需正常编码，工具自然会帮你调成正确样式。

第二道防线：提交前拦截

即便本地没开插件，或者有人绕过了编辑器检查，下一关是 Git 提交钩子。

借助 Husky 和 lint-staged，项目在package.json中定义了这样的规则：

"lint-staged": { "*.{ts,tsx,js,jsx}": [ "prettier --write", "eslint --fix" ] }

这意味着，只要你尝试提交代码，系统就会自动对暂存区的文件执行：

1. Prettier 写入式格式化（--write）
2. ESLint 自动修复可修正的问题（--fix）

只有完成这两步后，提交才会继续。换句话说，进入仓库的每一行代码，都已经过标准化处理。

而且 lint-staged 的聪明之处在于它只处理变更文件，而不是全量扫描，这样即使项目很大也不会拖慢提交速度。

第三道防线：CI 全面验证

最后，GitHub Actions 在 Pull Request 上运行完整的 lint 命令：

- name: Run ESLint run: npm run lint

这里的npm run lint通常是：

"lint": "eslint . --ext .ts,.tsx,.js,.jsx"

它会对整个代码库进行一次全面检查，确保没有任何遗漏。如果有任何文件不符合规则，CI 直接失败，PR 不允许合并。

这三层机制层层递进：
第一层提升体验，第二层防止疏忽，第三层兜底保障。三者结合，形成了近乎“零容忍”的质量控制体系。

实际收益：不只是格式统一

表面上看，这套方案解决的是“代码好不好看”的问题，但实际上带来的影响远不止于此。

尤其是在涉及 AI 功能开发时，这一点尤为重要。Excalidraw 正在探索通过自然语言生成图表的特性，这类功能往往需要动态拼接代码模板或生成组件结构。如果没有严格的 ESLint 检查，很容易产出不符合类型约束或存在引用错误的代码片段。而现在，哪怕是由 AI 生成的代码，也能在提交前被及时发现并修正。

此外，这种“配置即代码”的做法也让项目更具可持续性。所有规则都纳入版本控制，新人克隆仓库后只需安装依赖，就能获得完全一致的开发环境。不像有些项目，规范只存在于文档里，实际执行却千差万别。

设计背后的思考

Excalidraw 团队在落地这套方案时，并非一开始就追求极致严格。相反，他们采取了渐进式启用策略：初期只开启最关键、共识度最高的规则，避免一次性爆出上千个错误吓退贡献者。随着社区接受度提高，再逐步收紧标准。

这也反映出一种成熟的工程文化：工具服务于人，而非反过来。

另一个值得注意的点是性能优化。大型项目全量 lint 可能耗时数十秒，严重影响开发节奏。因此使用lint-staged仅处理变更文件，是一种非常务实的选择。对于超大项目，甚至可以进一步结合--max-warnings=0等选项精细化控制行为。

文档配套也同样重要。CONTRIBUTING.md明确写着：“提交前请确保通过 lint 检查”，并附带详细的设置指南。这让整个流程透明可预期，而不是靠口头相传。

写在最后

Excalidraw 的成功不仅仅在于它的手绘风格 UI 或协作体验，更体现在其背后严谨的工程实践。通过 ESLint 与 Prettier 的深度整合，项目实现了代码风格的高度一致性，而这恰恰是开源项目长期可维护性的基石。

更重要的是，这种方式体现了一种现代前端工程的价值观：用工具代替争论，用自动化释放创造力。

当每个人都无需纠结“要不要加分号”的时候，才能真正把精力投入到更有意义的事情上——比如设计更好的交互、优化协作延迟，或是让 AI 更懂用户的意图。

在这个意义上，代码规范不再是束缚，而是一种解放。