# JavaScript工程项目的一系列最佳实践|博客系列

> 本文系统总结了JavaScript工程项目开发中的最佳实践，包括Git分支管理、代码规范、构建流程、测试、持续集成等内容，帮助开发者提升项目质量与团队协作效率。

- 原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/javascript/-JavaScript%E5%B7%A5%E7%A8%8B%E9%A1%B9%E7%9B%AE%E7%9A%84%E4%B8%80%E7%B3%BB%E5%88%97%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5
- 来源：前端进阶之旅（feinterview.poetries.top）
- 更新：2025.10.25
- 可见范围：免费部分

---

## 1.Git

### 1.1 一些Git规则

> 这里有一套规则要牢记

**在功能分支中执行开发工作**

- 因为这样，所有的工作都是在专用的分支而不是在主分支上隔离完成的。它允许您提交多个 `pull request` 而不会导致混乱。您可以持续迭代提交，而不会使得那些很可能还不稳定而且还未完成的代码污染 `master` 分支

**从 `develop` 独立出分支**

- 这样，您可以保持 `master` 分支中的代码稳定性，这样就不会导致构建问题，并且几乎可以直接用于发布

**永远也不要将分支（直接）推送到 develop 或者 master
，请使用合并请求（Pull Request）**

- 通过这种方式，它可以通知整个团队他们已经完成了某个功能的开发。这样开发伙伴就可以更容易对代码进行 code review，同时还可以互相讨论所提交的需求功能

**在推送所开发的功能并且发起合并请求前，请更新您本地的develop分支并且完成交互式变基操作（interactive rebase）**

 - ebase 操作会将（本地开发分支）合并到被请求合并的分支（ master 或 develop ）中，并将您本地进行的提交应用于所有历史提交的最顶端，而不会去创建额外的合并提交（假设没有冲突的话），从而可以保持一个漂亮而干净的历史提交记录

**请确保在变基并发起合并请求之前解决完潜在的冲突**

- 合并分支后删除本地和远程功能分支
  - 如果不删除需求分支，大量僵尸分支的存在会导致分支列表的混乱。而且该操作还能确保有且仅有一次合并到master 或 develop。只有当这个功能还在开发中时对应的功能分支才存在

**在进行合并请求之前，请确保您的功能分支可以成功构建，并已经通过了所有的测试（包括代码规则检查）**

- 因为您即将将代码提交到这个稳定的分支。而如果您的功能分支测试未通过，那您的目标分支的构建有很大的概率也会失败。此外，确保在进行合并请求之前应用代码规则检查。因为它有助于我们代码的可读性，并减少格式化的代码与实际业务代码更改混合在一起导致的混乱问题

**使用 这个 `.gitignore `文件**

 - 此文件已经囊括了不应该和您开发的代码一起推送至远程仓库（remote repository）的系统文件列表。另外，此文件还排除了大多数编辑器的设置文件夹和文件，以及最常见的（工程开发）依赖目录

**保护您的 develop 和 master 分支**

- 这样可以保护您的生产分支免受意外情况和不可回退的变更

### 1.2 Git 工作流

> 基于以上原因, 我们将 功能分支工作流 ， 交互式变基的使用方法 结合一些 Gitflow中的基础 (比如，命名和使用一个develop branch)一起使用。 主要步骤如下

**针对一个新项目, 在您的项目目录初始化您的项目。 如果是（已有项目）随后的功能开发/代码变动，这一步请忽略**

```
cd <项目目录>
git init
```

**检出（Checkout） 一个新的功能或故障修复（feature/bug-fix）分支**

```
git checkout -b <分支名称>
```

**新增代码变更**

> git commit -a 会独立启动一个编辑器用来编辑您的说明信息，这样的好处是可以专注于写这些注释说明

```
git add
git commit -a
```

**（切换至功能分支并且）通过交互式变基从您的develop分支中获取最新的代码提交，以更新您的功能分支**

> 您可以使用 --autosquash 将所有提交压缩到单个提交。没有人会愿意（看到） develop 分支中的单个功能开发就占据如此多的提交历史

```
git checkout <branchname>
git rebase -i --autosquash develop
```

**如果没有冲突请跳过此步骤，如果您有冲突, 就需要解决它们并且继续变基操作**

```
git add <file1> <file2> ...
git rebase --continue
```

**推送您的（功能）分支。变基操作会改变提交历史, 所以您必须使用 -f 强制推送到远程（功能）分支。 如果其他人与您在该分支上进行协同开发，请使用破坏性没那么强的 --force-with-lease 参数**

> 当您进行 rebase 操作时，您会改变功能分支的提交历史。这会导致 Git 拒绝正常的 git push 。那么，您只能使用 -f 或 --force 参数了

```
git push -f
```

**提交一个合并请求（Pull Request）**

**Pull Request 会被负责代码审查的同事接受，合并和关闭**

**如果您完成了开发，请记得删除您的本地分支。**

```
git branch -d <分支>
```

**（使用以下代码）删除所有已经不在远程仓库维护的分支**

```javascript
git fetch -p && for branch in `git branch -vv | grep ': gone]' | awk '{print $1}'`; do git branch -D $branch; done
```

### 1.3 如何写好 Commit Message

> 坚持遵循关于提交的标准指南，会让在与他人合作使用 Git 时更容易。这里有一些经验法则 

**用新的空行将标题和主体两者隔开**

> Git 非常聪明，它可将您提交消息的第一行识别为摘要。实际上，如果您尝试使用 git shortlog ，而不是 git log ，您会看到一个很长的提交消息列表，只会包含提交的 id 以及摘要（，而不会包含主体部分）

**将标题行限制为50个字符，并将主体中一行超过72个字符的部分折行显示**

> 提交应尽可能简洁明了，而不是写一堆冗余的描述

**标题首字母大写**

**不要用句号结束标题**

**使用主体部分去解释 是什么 和 为什么 而不是 怎么做**

## 2. 文档

- 可以使用这个 模板 作为 [README （的一个参考）](https://github.com/wearehive/project-guidelines/blob/master/README.sample.md)
- 对于具有多个存储库的项目，请在各自的 README 文件中提供它们的链接
- 随项目的进展，持续地更新 README
- 给您的代码添加详细的注释，这样就可以清楚每个主要部分的含义
- 不要把注释作为坏代码的借口。保持您的代码干净整洁
- 也不要把那些清晰的代码作为不写注释的借口
- 当代码更新，也请确保注释的同步更新

## 3. 环境

**如果需要，请分别定义 development, test 和 production 三个环境**

> 不同的环境可能需要不同的数据、token、API、端口等。您可能需要一个隔离的 development 环境，它调用 mock 的 API，mock 会返回可预测的数据，使自动和手动测试变得更加容易。或者您可能只想在 production 环境中才启用 Google Analytics（分析）

**依据不同的环境变量加载部署的相关配置，不要将这些配置作为常量添加到代码库中**

> - 您会有令牌，密码和其他有价值的信息。这些配置应正确地从应用程序内部分离开来，这样代码库就可以随时独立发布，不会包含这些敏感配置信息
> - 怎么做： 使用 .env 文件来存储环境变量，并将其添加到 .gitignore 中使得排除而不被提交（到仓库）。另外，再提交一个 .env.example 作为开发人员的参考配置。对于生产环境，您应该依旧以标准化的方式设置环境变量

**建议您在应用程序启动之前校验一下环境变量** 

> 它可能会将其他人从上小时的故障排查中解救

```javascript
const joi = require('joi')

const envVarsSchema = joi.object({  
  NODE_ENV: joi.string()
    .valid(['development', 'production', 'test', 'provision'])
    .required(),
  PORT: joi.number()
    .required(),
  LOGGER_LEVEL: joi.string()
    .valid(['error', 'warn', 'info', 'verbose', 'debug', 'silly'])
    .default('info'),
  LOGGER_ENABLED: joi.boolean()
    .truthy('TRUE')
    .truthy('true')
    .falsy('FALSE')
    .falsy('false')
    .default(true)
}).unknown()
  .required()

const { error, value: envVars } = joi.validate(process.env, envVarsSchema)  
if (error) {  
  throw new Error(`Config validation error: ${error.message}`)
}

const config = {  
  env: envVars.NODE_ENV,
  isTest: envVars.NODE_ENV === 'test',
  isDevelopment: envVars.NODE_ENV === 'development',
  logger: {
    level: envVars.LOGGER_LEVEL,
    enabled: envVars.LOGGER_ENABLED
  },
  server: {
    port: envVars.PORT
  }
  // ...
}

module.exports = config;
```

### 3.1 一致的开发环境

**在 package.json 里的 engines 中设置您的node版本**

- 让其他人可以清晰的知道这个项目中用的什么node版本

**另外，使用 nvm 并在您的项目根目录下创建一个 .nvmrc 文件。不要忘了在文档中标注**

> 任何使用nvm的人都可以使用 nvm use 来切换到合适的node版本

**最好设置一个检查 `node` 和 `npm` 版本的 `preinstall` 脚本**

> 某些依赖项可能会在新版本的 npm 中安装失败。

**如果可以的话最好使用 Docker 镜像**

> 它可以在整个工作流程中为您提供一致的环境，而且不用花太多的时间来解决依赖或配置

**使用本地模块，而不是使用全局安装的模块**

> 您不能指望您的同事在自己的全局环境都安装了相应的模块，本地模块可以方便您分享您的工具

### 3.2 依赖一致性

**确保您的团队成员获得与您完全相同的依赖。**

> - 因为您希望代码在任何开发环境中运行都能像预期的一样
> - 在`npm@5`或者更高版本中使用 `package-lock.json`

- 我们没有 `npm@5`
  - 或者，您可以使用 `yarn` ，并确保在 `README.md` 中标注了使用 yarn 。您的锁文件和`package.json`在每次依赖关系更新后应该具有相同的版本

- 我不太喜欢 `Yarn`
  - 不喜欢 `Yarn`，太糟糕了。对于旧版本的`npm`，在安装新的依赖关系时使用 `-save --save-exact` ，并在发布之前创建`npm-shrinkwrap.json`

## 4. 依赖

**持续跟踪您当前的可用依赖包: 举个例子, `npm ls --depth=0`**

**查看这些软件包是否未使用或者与开发项目无关: depcheck**

> 您可能会在代码中包含未使用的库，这会增大生产包的大小。请搜索出这些未使用的依赖关系并去掉它们吧

**在使用依赖之前，请检查他的下载统计信息，看看它是否被社区大量使用： npm-stat**

> 更多的使用量很大程度上意味着更多的贡献者，这通常意味着拥有更好的维护，这些能确保错误能够被快速地发现并修复

**在使用依赖之前，请检查它是否具有良好而成熟的版本发布频率与大量的维护者：例如， npm view async**

> 如果维护者没有足够快地合并修补程序，那么这些贡献者也将会变得不积极不高效

**如果需要使用那些不太熟悉的依赖包，请在使用之前与团队进行充分讨论**

**始终确保您的应用程序在最新版本的依赖包上面能正常运行，而不是无法使用：npm outdated**

> 依赖关系更新有时包含破坏性更改。当显示需要更新时，请始终先查看其发行说明。并逐一地更新您的依赖项，如果出现任何问题，可以使故障排除更容易。可以使用类似 npm-check-updates 的酷炫工具

## 5. 测试

**如果需要，请构建一个 test 环境.**

> 虽然有时在 production 模式下端到端测试可能看起来已经足够了，但有一些例外：比如您可能不想在生产环境下启用数据分析功能，只能用测试数据来填充（污染）某人的仪表板。另一个例子是，您的API可能在 production 中才具有速率限制，并在请求达到一定量级后会阻止您的测试请求

**将测试文件放在使用 * .test.js 或 * .spec.js 命名约定的测试模块，比如 moduleName.spec.js**

> 您肯定不想进入一个层次很深的文件夹结构来查找里面的单元测试

**将其他测试文件放入独立的测试文件夹中以避免混淆**

> 一些测试文件与任何特定的文件实现没有特别的关系。您只需将它放在最有可能被其他开发人员找到的文件夹中：__test__ 文件夹。这个名字：__test__也是现在的标准，被大多数JavaScript测试框架所接受

**编写可测试代码，避免副作用（side effects），提取副作用，编写纯函数**

- 您想要将业务逻辑拆分为单独的测试单元。您必须“尽量减少不可预测性和非确定性过程对代码可靠性的影响”
- 纯函数是一种总是为相同的输入返回相同输出的函数。相反地，不纯的函数是一种可能会有副作用，或者取决于来自外部的条件来决定产生对应的输出值的函数。这使得它不那么可预测

**使用静态类型检查器**

- 有时您可能需要一个静态类型检查器。它为您的代码带来一定程度的可靠性

**先在本地 develop 分支运行测试，待测试通过后，再进行pull请求**

- 您不想成为一个导致生产分支构建失败的人吧。在您的rebase之后运行测试，然后再将您改动的功能分支推送到远程仓库。

**记录您的测试，包括在 README 文件中的相关说明部分**

- 这是您为其他开发者或者 DevOps 专家或者 QA 或者其他如此幸运能和您一起协作的人留下的便捷笔记

## 6. 结构布局与命名

**请围绕产品功能/页面/组件，而不是围绕角色来组织文件。此外，请将测试文件放在他们对应实现的旁边**

- 不规范

```
.
├── controllers
|   ├── product.js
|   └── user.js
├── models
|   ├── product.js
|   └── user.js
```

- 规范

```
.
├── product
|   ├── index.js
|   ├── product.js
|   └── product.test.js
├── user
|   ├── index.js
|   ├── user.js
|   └── user.test.js
```

> 比起一个冗长的列表文件，创建一个单一责权封装的小模块，并在其中包括测试文件。将会更容易浏览，更一目了然

**将其他测试文件放在单独的测试文件夹中以避免混淆**

- 这样可以节约您的团队中的其他开发人员或DevOps专家的时间

**使用 ./config 文件夹，不要为不同的环境制作不同的配置文件。**

> 当您为不同的目的（数据库，API等）分解不同的配置文件;将它们放在具有容易识别名称（如 config ）的文件夹中才是有意义的。请记住不要为不同的环境制作不同的配置文件。这样并不是具有扩展性的做法，如果这样，就会导致随着更多应用程序部署被创建出来，新的环境名称也会不断被创建，非常混乱。 配置文件中使用的值应通过环境变量提供

**将脚本文件放在./scripts文件夹中。包括 bash 脚本和 node 脚本。**

- 很可能最终会出现很多脚本文件，比如生产构建，开发构建，数据库feeders，数据库同步等

**将构建输出结果放在./build文件夹中。将build/添加到.gitignore中以便忽略此文件夹**

---

> 以上是免费部分。完整内容需要「前端进阶之旅」会员，原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/javascript/-JavaScript%E5%B7%A5%E7%A8%8B%E9%A1%B9%E7%9B%AE%E7%9A%84%E4%B8%80%E7%B3%BB%E5%88%97%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5
