前端基建是啥玩意

Category（分类）: Other Status: 持续更新

原文写于前端工程化快速发展的阶段，主要从 DevOps、协作、代码规范、组件库和沟通工具几个角度讨论中小团队如何搭建前端基建。本文尽量保留原文的实践视角，同时把已经过时的 Husky、CI 配置、工具推荐和绝对化表述更新为现在更稳妥的做法。

前端基建不是把一堆工具装进项目，也不是为了“看起来专业”而增加流程。它的目标是让团队更稳定、更快地交付，并且让项目更容易被接手和维护。

原文参考：快速打造中小团队的前端基建 - 协作篇

一、前端基建到底是什么

可以把前端基建理解为围绕“代码从想法到线上运行”建立的一套约定、工具、自动化流程、公共物料和运行保障，包括但不限于：

项目脚手架、目录约定和本地开发环境；
包管理、依赖锁定、构建和发布工具；
ESLint、格式化、类型检查和提交规范；
组件库、设计令牌、工具函数和业务 SDK；
Mock、接口契约、测试和质量门禁；
CI/CD、预览环境、部署、回滚和监控；
文档、协作流程、权限管理和知识沉淀。

它不是某一个框架，也不是“Webpack 配置大全”。前端基建更接近一条让开发者少走弯路的 paved road（铺装道路）：默认路径简单可靠，特殊需求仍然允许有明确的逃生口。

二、从 DevOps 看前端基建

原文 DevOps 配图

DevOps 不是一个产品名称，而是一种让开发、测试、运维和业务共同负责交付与运行结果的协作方式。前端虽然主要编写浏览器代码，但仍然会参与完整的软件交付周期：

需求与设计 → 开发 → 构建 → 测试 → 发布 → 运行监控 → 反馈改进

一套简化的前端 DevOps 流程通常包含：

协作：需求、设计、接口、代码评审和问题追踪；
构建：安装依赖、编译、打包、生成静态资源；
测试：Lint、类型检查、单元测试、组件测试和端到端测试；
部署：预览环境、灰度、生产发布和回滚；
运行：错误监控、性能监控、日志、告警和事故复盘。

常见概念需要区分：

持续集成（CI）：代码变更后自动构建和验证，尽早发现问题；
持续交付（Continuous Delivery）：通过验证的版本随时可以发布，发布通常仍有人工确认；
持续部署（Continuous Deployment）：通过自动化门禁后自动部署到生产；
DevOps：不只是 CI/CD，还包括协作、反馈、运营和责任边界。

DevOps 的核心目标仍可以概括为“快速交付价值，灵活响应变化”，但“快速”不等于跳过测试和审查，“自动化”也不等于把所有事情都交给脚本。真正应该自动化的是重复、明确、容易出错的步骤。

三、中小团队应该先解决什么

中小团队不需要第一天就搭建一个巨大的平台。可以按风险和收益逐步建设：

1. 最小可用基建

明确 Node.js、包管理器和锁文件；
有可运行的 dev、lint、test、build 命令；
提交前检查格式和明显错误；
Pull Request/Merge Request 必须经过 CI；
有 README、环境变量说明和部署说明；
生产发布可回滚，线上错误有人能看到。

2. 团队扩大后的基建

抽离共享 ESLint、TypeScript、Prettier 和测试配置；
建立组件库、设计令牌和 Storybook；
用 OpenAPI/JSON Schema 等契约减少接口扯皮；
使用预览环境、自动化端到端测试和依赖更新；
统一错误监控、性能指标和发布记录。

3. 多项目或多包团队

评估 monorepo 和 workspace，统一依赖与脚本；
使用 workspace: 协议明确引用本地包；
为公共包设计 API、版本策略、变更日志和发布流程；
用 Changesets 或同类工具管理多包版本；
将平台能力做成模板、共享配置或内部服务，而不是复制粘贴。

基建建设应当有指标。例如：新项目初始化时间、CI 平均耗时、回滚耗时、线上错误发现时间、依赖升级周期、公共组件复用率等。没有指标就很容易变成“大家都觉得很忙，但不知道是否变好”。

四、团队内协作：先统一规则，再统一工具

原文提到的典型问题今天依然存在：

原文协作配图

成员水平不同，代码风格各不相同；
不同项目的构建配置和请求封装差异过大；
同一套 UI 被复制到多个项目，修复一次要改很多份；
代码没有注释，项目没有文档，新人难以接手；
依赖和 Node 版本不一致，导致“我这里可以运行”。

1. 代码仓库和分支协作

建议在团队约定中明确：

默认分支受保护，生产发布只能从经过审查的分支或标签进行；
使用 PR/MR 做代码评审，不要把评审变成形式化的“点一下通过”；
明确变更范围、截图、测试结果、回滚方式和关联需求；
对高风险目录设置 CODEOWNERS 或责任人；
重要决策写入 ADR（Architecture Decision Record），不要只留在聊天记录里；
README、CONTRIBUTING、CHANGELOG、部署文档和故障处理手册随代码维护。

分支模型可以选 GitHub Flow、GitLab Flow、Trunk-based Development 等，重点是适合团队发布频率和权限模型，而不是争论哪一种“最先进”。

2. 依赖和运行环境统一

在仓库中明确 Node.js 和包管理器版本，例如使用 .nvmrc、.tool-versions、Volta 或 package.json 的 engines / packageManager 字段。团队已经选择 pnpm 时，就不要在同一项目里混用 npm、yarn 或 bun。

常见约定：

.nvmrc
package.json
pnpm-lock.yaml

安装依赖时使用锁文件对应的不可变安装：

pnpm install --frozen-lockfile

锁文件不是“可有可无的缓存”，它记录了解析后的依赖版本，有助于让本地、CI 和生产构建得到一致结果。依赖更新应通过 Pull Request、变更说明和安全扫描完成，不能随意删除锁文件解决冲突。

3. API 和设计协作

“后端必须全部使用 RESTful，否则项目一定失败”是过于绝对的说法。REST、RPC、GraphQL 和事件接口都可以工作，关键是契约清晰、错误可处理、兼容策略明确。

建议：

用 OpenAPI 描述 HTTP API，用 JSON Schema 或类似方案描述数据结构；
用 Swagger UI、Redoc 等工具展示和调试 OpenAPI 文档；Swagger 是工具生态，不是 API 风格本身；
约定状态码、分页、时间、金额、空值、错误码、鉴权和幂等性；
根据契约生成 Mock、类型、客户端或测试，而不是把接口文档只放在 Word 里；
对破坏性变化采用版本、兼容窗口或迁移策略；
让产品、设计、前端、后端和测试在开发前共同确认关键流程和边界条件。

Mock 可以使用契约 Mock、服务端测试环境或 MSW 等方案。Mock 的目的不是掩盖接口不稳定，而是让前端能够并行开发，并在真实接口接入前发现数据结构问题。

五、三层代码质量约束

原文把代码质量分为 ESLint、Git Hooks 和 CI 三层，这个思路仍然实用，但三层的职责需要分清：

1. 第一层：编辑器和本地命令

可以采用 ESLint、Prettier、Stylelint、TypeScript 等工具。当前 ESLint 推荐使用根目录的 eslint.config.js 等 Flat Config 文件，而不是继续照搬早期 .eslintrc 示例：

// eslint.config.js
import js from '@eslint/js'
import { defineConfig } from 'eslint/config'

export default defineConfig([
  {
    files: ['**/*.{js,mjs,cjs,ts}'],
    extends: [js.configs.recommended]
  }
])

实际项目还应按 Vue、React、TypeScript 等技术栈添加对应插件和解析器。Airbnb、Google、Standard 等是可参考的共享规则，不是必须全盘照搬的标准；规则应服务于可读性、错误发现和团队一致性。

建议使用统一脚本入口，不让每个人手动拼很长的命令：

{
  "scripts": {
    "lint": "eslint .",
    "format:check": "prettier --check .",
    "typecheck": "vue-tsc --noEmit",
    "test": "vitest run",
    "build": "nuxt build"
  }
}

脚本名称和技术栈应按项目实际情况调整；不存在的脚本不要硬塞进公共模板。

原文 ESLint 配图

2. 第二层：Git Hooks

Git Hooks 可以在提交前运行格式、Lint、类型检查或提交信息校验。Husky 仍然常用，但原文的 husky.hooks 配置属于 Husky v4 时代，HUSKY_GIT_PARAMS 等写法不能直接套用到当前版本。

当前 Husky 的初始化方式示意：

pnpm add --save-dev husky
pnpm exec husky init

它会创建 .husky/pre-commit 并更新 package.json 的 prepare 脚本。钩子中可以运行 pnpm lint，也可以配合 lint-staged 只检查暂存文件：

# .husky/pre-commit
pnpm exec lint-staged

提交信息可选用 Conventional Commits，例如：

feat: add article search
fix: handle empty article path
chore: update dependencies

常见类型包括 feat、fix、docs、chore、refactor、perf、test 和 ci。提交规范是协作约定，不应阻止团队根据实际情况添加 scope 或其他类型。

原文 Git Hooks 配图

需要特别注意：本地 Hook 可以被 --no-verify、环境变量或手动操作跳过。它适合提供快速反馈，但不是安全边界，也不能作为“无论如何都无法绕过”的校验。

3. 第三层：CI 和分支保护

CI 在服务端执行，因此比本地 Hook 更可靠。对合并到主分支或发布分支的变更，应配置必需的状态检查、评审人数、分支保护和发布权限。管理员权限、错误的权限配置和被泄露的 CI 凭据仍然可能绕过流程，所以还要做好最小权限和审计。

原文中的 GitLab 配置有 YAML 格式和命令错误，例如 stage:lint、-npmlint 都不是推荐写法。一个简化的 GitLab CI 示例可以写成：

stages:
  - verify
  - build

default:
  image: node:<团队批准的版本>
  before_script:
    - npm install --global pnpm@<团队批准的版本>
    - pnpm install --frozen-lockfile

verify:
  stage: verify
  script:
    - pnpm lint
    - pnpm typecheck
    - pnpm test

build:
  stage: build
  script:
    - pnpm build
  artifacts:
    paths:
      - dist/ # Nuxt 等框架按实际情况改为 .output/

尖括号内容只是占位符，实际配置必须换成团队批准并经过验证的版本。这里的 npm 仅用于在干净的 Node 镜像中安装 pnpm CLI，不参与项目依赖管理；也可以使用已预装并固定 pnpm 版本的 CI 镜像。项目依赖仍应全程使用 pnpm。GitLab 的 CI Lint 可以先验证 YAML 和基本配置；GitHub Actions、GitLab CI、Jenkins 等都可以实现同样的流程。

原文 CI 配图

CI 的验证内容可以包括：

依赖是否能按锁文件安装；
ESLint、Prettier、Stylelint 和类型检查；
单元、组件和端到端测试；
构建产物是否生成、大小是否超预算；
依赖漏洞、许可证和机密信息扫描；
部署前的冒烟检查和可回滚性。

六、统一前端物料：组件、工具和 SDK

1. 组件库与 Storybook

团队有统一 UI 风格时，可以把基础组件、设计令牌和业务无关的交互抽离为共享包。不要一开始就把所有业务页面塞进组件库，否则组件会被业务规则绑死，升级困难。

Storybook 适合独立开发、展示和测试组件状态。它提供隔离的开发环境，可以记录组件的加载中、空数据、错误、权限不足、响应式和无障碍等状态。

原文 Storybook 配图

一个较稳妥的步骤是：

先识别真实重复且稳定的 UI 模式；
抽离设计令牌、基础组件和可复用交互；
为组件编写 stories，覆盖正常、边界和异常状态；
使用 Testing Library、Vitest、Playwright、axe 等工具做交互、视觉和无障碍检查；
在 CI 中构建和发布 Storybook，作为团队可搜索的组件文档；
通过版本和变更记录控制组件升级，不要让业务项目无感地被破坏。

Storybook 是开发和文档工具，不会自动保证组件设计正确；它也不能替代真实业务流程测试。

2. 工具函数和第三方 SDK

“每个项目都统一使用同一个库”不一定是正确目标，更重要的是减少重复、控制依赖风险并明确选择理由：

Moment.js 已进入维护模式，新的项目可以评估 Intl.DateTimeFormat、Temporal polyfill 或 Day.js 等方案，但要根据时区、国际化和包体积需求选择；
Immer 和 Immutable.js 解决的问题和数据模型并不完全相同，不能简单说谁必然替代谁；
小工具只有在语义稳定、测试充分、维护成本低时才值得内部共享；
第三方 SDK 应有封装层，避免业务代码直接依赖供应商 API；
记录包体积、许可证、维护状态、漏洞和升级负责人；
不要为“统一”而保留一个已经无人维护的内部库。

公共包应有清晰入口、类型、文档、测试、SemVer 版本和迁移说明。公共包变更要考虑多个消费者，不要把业务项目的临时需求直接写进底层包。

TypeScript、Vue/React 等源码转换；
开发服务器和热更新；
代码分割、Tree Shaking 和资源压缩；
静态资源哈希、缓存和 CDN 发布；
source map、环境配置和构建诊断。

2. 可复现构建

建议做到：

使用锁文件和不可变安装；
在 CI 和本地统一 Node、pnpm 及构建参数；
缓存 pnpm store 或 CI 依赖，但不要缓存不一致的构建结果；
构建失败时保留日志、测试报告和必要的产物；
不把 .env 中的生产密钥提交到仓库；
明确哪些环境变量会进入浏览器包：进入前端包的值都不能当作秘密。

3. 资源和性能预算

对 JavaScript 初始包、CSS、图片、字体、页面 LCP 和构建时间设置预算。预算超标时让 CI 给出告警或阻断，而不是上线后才发现首屏变慢。

静态资源通常使用内容哈希文件名并设置长期缓存：

Cache-Control: public, max-age=31536000, immutable

HTML 入口和包含运行时配置的响应通常需要较短缓存或重新验证。不同应用的缓存策略不同，不能把 immutable 盲目加到所有响应上。

八、测试体系：从便宜到昂贵

测试不是“写满 100% 覆盖率”，而是用合理成本保护重要行为：

层级	适合检查的内容	常见工具
静态检查	风格、明显错误、类型	ESLint、Prettier、TypeScript
单元测试	纯函数、状态转换、边界条件	Vitest、Jest
组件测试	交互、状态和可访问性	Testing Library、Storybook
视觉测试	像素和主题回归	Storybook、Chromatic 等
端到端测试	登录、支付、关键业务流程	Playwright、Cypress
线上监控	真实用户错误和性能	RUM、错误监控、日志平台