文章目录
- 项目指南：写给 JavaScript 团队的工程规范手册
- 开发新项目很爽，维护才是噩梦
- 涵盖哪些内容
- 代码风格和强制执行
- 这份指南适合谁
项目指南：写给 JavaScript 团队的工程规范手册
elsewhencode/project-guidelines 这个仓库在 GitHub 上有 29,458 个 Star。
它不是框架，不是工具库，不是脚手架。它是一份文档，专门回答一个问题：JavaScript 项目该怎么组织，才能让第二个人接手的时候不骂人。
开发新项目很爽，维护才是噩梦
每个写过代码的人都有过这种经历：项目初期进展飞快，功能一个接一个往上加，目录结构随心所欲，commit 信息写得像日记。三个月后回来改 bug，发现看不懂自己写的代码，找不到文件在哪，git log 里全是 “fix” 和 “update”。
这个仓库就是来解决这类问题的。它由 elsewhen 团队整理，把他们在多个 JavaScript 项目中积累的经验写成了可执行的规范。不是理论文章，是直接拿来用的清单。
涵盖哪些内容
整个指南分成 11 个部分，每个部分都是一个独立的工程实践领域。
Git 工作流部分规定了分支策略：功能开发在 feature branch 上进行，从 develop 分支拉出，完成后通过 PR 合并。它还详细说明了 rebase 的用法、commit message 的格式要求，比如主题行不超过 50 个字符，使用祈使语气，正文解释做了什么和为什么而不是怎么做。
环境管理部分强调配置与代码分离。环境变量通过 .env 文件管理，.env 本身加入 .gitignore，只提交 .env.example 作为模板。生产环境的配置不写死在代码里，用环境变量注入。
依赖管理部分有一套筛选流程：用一个包之前先看下载量，再看维护者数量和版本发布频率，不熟悉的包先和团队讨论。定期跑 npm outdated 检查更新，用 Snyk 扫描已知漏洞。
测试部分要求测试文件放在被测模块旁边，文件名用 .test.js 或 .spec.js 后缀。写可测试的代码，避免副作用，提取纯函数。PR 提交前必须在本地跑通测试。
目录结构部分反对按角色（controllers、models、services）组织文件，主张按功能模块组织。一个功能的所有相关文件放在一起，包括它的测试。
代码风格和强制执行
代码风格部分推荐使用 ESLint，参考 Airbnb JavaScript Style Guide。不是建议，是强制：把代码风格检查嵌入构建流程，构建不通过就不让提交。
它还建议使用 .editorconfig 文件统一编辑器配置，用 Prettier 配合 precommit hook 自动格式化。这样团队成员不管用什么编辑器，出来的代码风格都一样。
这份指南适合谁
在 JavaScript 团队里工作、需要统一工程规范的人。刚接手一个项目、想快速建立开发流程的人。或者单纯想看看别人家团队是怎么做工程化的，都可以翻一翻。
它不教你写代码，它教你把写代码这件事变得可控。
么做工程化的，都可以翻一翻。
它不教你写代码，它教你把写代码这件事变得可控。
