「Ant Design 组件库探索」一：整体结构+工程化设置

李仲轩
446 阅读27分钟

大家好，好久没更新文章了，从今天开始呢，要准备开一个新坑了，那就是更新Ant Design（5.25.0）组件库探索系列；为什么要做这个东西，是因为准备学习优秀的开源项目来的。我的解读是按照自己的探索思路来的，不一定全面，某种程度上也是自己的学习笔记，所以如果你对此不介意并且感兴趣，也欢迎订阅此专栏

前言

本篇文章是学习了整体结构以及工程化配置后的总结，所以内容很长，不用从头读到尾，请结合实际项目和兴趣点进行分节点阅读。

整体项目结构

  • .cursor/ ：编辑器或团队协作相关配置。
  • .devcontainer/ ：开发容器配置。
  • .dumi/ ：Dumi 文档工具相关目录。
  • .github/ ：GitHub 配置（如工作流、模板等）。
  • .husky/ ：Git 钩子工具 Husky 配置。
  • alias/ ：别名相关配置或工具。
  • components/ ：Ant Design 组件源码目录。
  • docs/ ：项目文档目录。
  • scripts/ ：脚本工具目录。
  • tests/ ：测试用例目录。
  • typings/ ：类型声明文件目录。
  • .antd-tools.config.js ：Ant Design 工具链配置文件。
  • .depslintrc.js ：依赖检查或代码规范相关配置。
  • .dockerignore ：Docker 构建忽略文件。
  • .editorconfig ：跨编辑器代码风格配置。
  • .gitignore ：Git 忽略文件配置。
  • .gitpod.yml ：Gitpod 云开发环境配置。
  • .jest.image.js .jest.js .jest.node.js .jest.site.js ：Jest 测试配置。
  • .lintstagedrc.json ：lint-staged 工具配置。
  • .ncurc.js ：npm-check-updates 配置。
  • .npmignore .npmrc ：npm 相关配置。
  • .prettierignore .prettierrc ：Prettier 代码格式化配置。
  • .remarkrc.js ：remark 文档处理工具配置。
  • .surgeignore ：Surge 部署忽略文件配置。
  • BUG_VERSIONS.json ：记录有 bug 的版本信息。
  • CHANGELOG.en-US.md CHANGELOG.zh-CN.md ：项目变更日志。
  • CNAME ：自定义域名配置（如 GitHub Pages）。
  • CODE_OF_CONDUCT.md ：行为准则。
  • LICENSE ：开源许可证。
  • README-zh_CN.md README.md ：项目说明文档。
  • SECURITY.md ：安全相关说明。
  • biome.json ：Biomes 相关配置（如代码风格）。
  • codecov.yml ：代码覆盖率工具配置。
  • contributors.json ：贡献者信息。
  • eslint.config.mjs ：ESLint 代码检查配置。
  • index-style-only.js index-with-locales.js index.js ：入口文件。
  • jest-puppeteer.config.js ：Puppeteer 测试配置。
  • mako.config.json ：Mako 工具配置。
  • package.json ：项目依赖和脚本配置。
  • renovate.json ：Renovate 依赖更新工具配置。
  • tsconfig-old-react.json tsconfig.json ：TypeScript 配置文件。
  • webpack.config.js ：Webpack 构建配置。

本期不分析业务代码，本期的重点是结构梳理和工程化设置。

目录+文件分析

以上的文件和目录经过分析后，在工程化处理中，本项目主要分为以下几个类别：

  • AI IDE设置
  • 依赖管理
  • 环境统一维护
  • 文档站点处理
  • Github设置
  • 测试相关
  • git管理
  • 代码约束
  • Markdown格式检查
  • 打包工具

接下来的分析，不会将源文件的文件内容进行展示，建议开一个IDE打开这个项目，对照着阅读。

AI IDE设置

这里的IDE设置主要是针对cursor的，看得出来，cursor是非常的火，这个库也支持了；这个cursor的目录结构是这样的：

.cursor/
└── rules/
    ├── demo.mdc
    ├── docs.mdc
    ├── git.mdc
    ├── locale.mdc
    ├── naming.mdc
    ├── project.mdc
    ├── styling.mdc
    ├── testing.mdc
    └── typescript.mdc

这是一个 cursor 编辑器的特点文件夹，.cursor/rules/目录下的文件是 Cursor 编辑器的规则配置文件，采用特定的格式来定义编辑器行为。

以其中一个 testing.mdc 文件为例：

---
description:
globs: **/__tests__/**,**/*.test.tsx,**/*.test.ts
alwaysApply: false
---
 # 测试规范

- 使用 Jest 和 React Testing Library 编写单元测试
- 对 UI 组件使用快照测试 (Snapshot Testing)
- 测试覆盖率要求 100%
- 测试文件放在 __tests__ 目录，命名格式为：index.test.tsx 或 xxx.test.tsx

它的格式和作用如下：

  • 文件格式 ：

    • 使用 YAML front matter(以 --- 包裹)定义元数据
    • 后面跟随 Markdown 格式的规则说明
    • 文件扩展名为.mdc(Markdown with front matter)

  • 关键字段 ：

    • description : 规则描述
    • globs : 匹配的文件模式
    • alwaysApply : 是否总是应用

  • 工作原理 ：

    • Cursor 读取这些规则文件
    • 根据 globs 匹配目标文件
    • 应用文件中定义的规则和规范

  • 为什么用这种格式 ：

    • YAML front matter 便于机器解析配置
    • Markdown 部分便于人类阅读和维护
    • 结合了配置的可读性和灵活性

  • 实际效果 ：

    • 对匹配的文件提供代码提示和规范检查
    • 在编辑器中显示相关规则说明
    • 帮助团队保持代码风格一致

依赖管理

这里的依赖管理涉及到四个文件，他们都是来对项目的依赖进行处理的，有的是本地命令，有的是配合github提交线上PR，有的是让依赖下载更快：

  • .depslintrc.js
  • ncurc.js
  • npmrc
  • renovate.json

接下来一一介绍。

.depslintrc.js

.depslintrc.js 文件在 ant-design 项目中主要作为依赖检查工具的配置文件，其作用机制如下：

  1. 依赖检查优化 ：

    • 通过 ignore 配置排除不必要的目录/文件检查，提高检查效率
    • 忽略测试文件(~\*/ )、样式文件(style/ )、本地化文件(locale/\*\*)等

  2. 模块映射处理 ：

    • 使用 modulePattern 定义特定模块引用模式的映射规则
    • 例如将 ConfigContext.renderEmpty 等模式映射到 ../empty 模块

  3. 工具集成 ：

    • 被 antd-tools 等构建工具调用（参考 package.json 中的 scripts）
    • 在 lint:deps 等脚本执行时生效，使用 gulp 来进行任务处理，匹配脚本命令

  4. 项目结构适配 ：

    • 配置与项目目录结构匹配（如 components/empty 目录）
    • 避免对组件库内部模块引用产生误报 该配置文件通过精准控制依赖分析范围，确保构建和检查过程既全面又高效。

ncurc.js

.ncurc.js 是 npm-check-updates（简称 ncu） 工具的配置文件，用于自定义依赖包升级的行为，核心功能就是直接修改package.json文件中依赖包的版本号。

npm-check-updates （简称 ncu）是一个独立的命令行工具。它的主要作用是：

  • 自动检查并显示 package.json 中依赖包的最新版本（包括主版本号的升级），而 npm 默认只会升级到 package.json 允许的最大版本。
  • 可以一键将 package.json 里的依赖更新到最新版本（通过 npx npm-check-updates -u ），然后再用 npm install 安装。
  • 支持多种自定义过滤、目标版本、依赖类型等高级用法。 它不会自动在 npm 安装、发布等生命周期中触发（不是钩子），而是需要开发者手动运行命令来检查和升级依赖。

文件内容具体解释如下：

  • packageFile: 指定要检查和升级的 package.json 路径。
  • upgrade: false: 默认不自动升级 package.json，需要手动运行 npx npm-check-updates -u 才会升级。
  • packageManager: 'npm': 指定使用 npm 作为包管理器。
  • dep: ['prod']: 只检查生产依赖（dependencies），不检查 devDependencies。
  • filter: 过滤函数，仅允许以 @ant-design/、@rc-component/、rc- 开头的依赖被检查和升级，并且排除了 @ant-design/cssinjs（即该包不会被 ncu 检查和升级）。
  • target: 指定升级目标为 semver，即遵循语义化版本。

这样配置的目的是：只关注 ant-design 及相关生态的生产依赖升级，避免误升级其它依赖或特殊包（如 cssinjs），并且升级操作需手动触发，保证依赖升级的可控性。

npmrc

.npmrc 是 npm 的配置文件，用于自定义 npm 的行为，存在优先级关系，如果项目中没有这个文件，那么就会用npm默认的设置。

以下是 .npmrc 文件配置的详细解读：

package-lock=false
legacy-peer-deps=true
PUPPETEER_DOWNLOAD_BASE_URL="https://cdn.npmmirror.com/binaries/chrome-for-testing"
npm_config_sharp_libvips_binary_host="https://cdn.npmmirror.com/binaries/sharp-libvips"
  1. package-lock=false：禁用 package-lock.json 文件的生成和更新。适用于组件库等不希望锁定依赖树的场景。
  2. legacy-peer-deps=true：安装依赖时忽略 peerDependencies 冲突，采用 npm v6 的旧行为，避免因 peer 依赖不兼容导致安装失败。
  3. PUPPETEER_DOWNLOAD_BASE_URL=...：指定 Puppeteer 下载 Chromium 的镜像源，加速国内环境下的依赖安装。
  4. npm_config_sharp_libvips_binary_host=...：指定 sharp 库依赖的 libvips 二进制文件下载镜像，加速依赖安装，解决网络问题。

这些配置主要用于提升依赖安装的兼容性和速度，适配国内开发环境。

renovate.json

renovate.json 是 Renovate Bot 的配置文件，用于自动化管理和更新项目依赖。

主要作用和配置说明如下：

  • automerge: 是否自动合并依赖更新的 PR，这里为 false，即需要人工审核合并。
  • dependencyDashboard: 启用依赖仪表盘，方便集中管理依赖更新。
  • rebaseWhen: 设置为 conflicted，表示当 PR 有冲突时自动 rebase。
  • ignoreDeps: 忽略的依赖列表，这里为空，表示不忽略任何依赖。
  • labels: 给依赖更新 PR 添加标签，这里为 dependencies。
  • postUpdateOptions: 更新后执行的操作，这里为 yarnDedupeHighest，即 yarn 去重依赖。
  • prConcurrentLimit: 同时存在的依赖更新 PR 数量上限，这里为 30。
  • prHourlyLimit: 每小时最多创建的 PR 数量，这里为 0，表示不限制。
  • schedule: 依赖更新的时间安排，这里为每周日早上 6 点前。
  • timezone: 时区设置为 UTC。
  • packageRules: 针对特定依赖包的自定义规则，这里对 @rc-component/*、rc-*、@ant-design/* 相关依赖分组，但设置为 enabled: false，即暂不启用。

整体来说，这个文件用于规范和自动化依赖升级流程，提升依赖管理效率，减少人工维护成本。

Renovate Bot 是一个自动化依赖管理工具，主要用于帮助项目自动检测、更新和维护依赖包的版本。它会定期扫描项目中的依赖（如 npm、yarn、pip 等），并根据配置自动创建更新依赖的 Pull Request，提醒开发者及时升级依赖，修复安全漏洞或兼容性问题。通过配置文件（如 renovate.json），可以灵活控制自动合并、分组、排除特定依赖、更新频率等行为，从而提升依赖管理的效率和安全性。

Renovate Bot 的详细工作流程如下：

  1. 配置初始化：

    • 项目根目录下添加 renovate.json 或 .github/renovate.json 配置文件，定义依赖更新策略、分组、自动合并、排除规则等。
    • 在代码托管平台（如 GitHub、GitLab）安装并授权 Renovate Bot。

  2. 定时扫描：

    • Renovate Bot 会根据配置的时间表（如每周、每天）自动扫描项目仓库，分析 package.json、yarn.lock、package-lock.json 等依赖文件，检测所有依赖的当前版本和可用的最新版本。

  3. 依赖分析与策略匹配：

    • Bot 会根据配置文件中的规则（如哪些依赖需要分组、哪些依赖不自动升级、哪些需要人工审批等）对检测到的依赖进行分类和处理。
    • 支持多种包管理器（npm、yarn、pip、maven 等），并能识别 monorepo、多包项目结构。

  4. 生成更新计划：

    • 对于有新版本的依赖，Renovate 会生成更新计划，决定是单独为每个依赖创建 PR，还是将多个依赖合并到一个 PR，根据 packageRules 或 groupName 等配置灵活分组。

  5. 创建 Pull Request（PR）：

    • Bot 自动在仓库中创建依赖升级的 PR，PR 内容包括升级说明、变更日志、兼容性提示等。
    • PR 会自动触发 CI 流程，确保升级不会破坏现有功能。
    • 支持自动 rebase、自动关闭冲突 PR、自动合并（如配置了 automerge）。

  6. 依赖仪表盘与通知：

    • Renovate 会在仓库中生成依赖仪表盘（Dependency Dashboard），集中展示所有待升级依赖和 PR 状态，方便维护者统一管理。
    • 通过邮件、平台通知等方式提醒开发者关注依赖升级。

  7. 合并与后续处理：

    • 维护者可根据 CI 结果和实际需求选择合并 PR，合并后依赖即完成升级。
    • 支持合并后自动执行 dedupe、锁文件更新等操作。

  8. 持续循环：

    • Renovate 会持续定期扫描和更新，确保项目依赖始终保持最新和安全。

总结：Renovate Bot 实现了依赖检测、升级、PR 创建、自动合并、通知和依赖仪表盘等全流程自动化，大幅降低了依赖维护的人力成本，提升了项目安全性和可维护性。

环境统一维护

这里的环境统一维护主要是指的保证一致的环境，避免出现在我的机器上能跑，在别人的机器不能跑的情况，主要有两个点：

  • .devcontainer（docker）
  • .gitpod.yml（云开发环境）

.devcontainer

这个 devcontainer.json 文件是用于配置 VS Code开发容器(Dev Container) 的配置文件，主要作用包括：

  1. 基础镜像配置 ：

    • 使用微软官方提供的TypeScript+Node.js开发镜像
    • 基于Debian Bookworm系统
    • 预装Node.js和TypeScript环境

  2. 初始化命令 ：

    "postCreateCommand": "pnpm install"
    • 容器创建后自动执行 pnpm install 安装依赖

  3. VS Code扩展配置 ：

    "extensions": [
  "dbaeumer.vscode-eslint",        // ESLint支持
  "shezhangzhang.antd-design-token", // Ant Design Token工具
  "fi3ework.vscode-antd-rush"      // Ant Design Rush工具
]

  4. 使用场景 ：

    • 为Ant Design项目提供一致的开发环境
    • 支持通过VS Code远程容器功能开发
    • 确保团队成员环境统一

对Dev Container这个不了解的，可以通过这两个文章进行了解：

简单一句话就是，Dev Container 是在容器中进行开发的一种方式。它的主要目的是提供一个标准化的开发环境，使得开发者可以在不同的操作系统、不同的开发工具和不同的开发环境中保持一致的开发体验。

.gitpod.yml

.gitpod.yml 是 Gitpod 的配置文件，它定义了 Gitpod 工作区的配置和初始化脚本。在 Ant Design 项目中，这个文件主要用于配置 Gitpod 工作区的环境和初始化脚本。

# 端口配置
ports:
  - port: 8001 # 暴露的端口号
    onOpen: open-preview # 端口打开时自动预览

# 任务配置
tasks:
  - before: > # 任务执行前的命令
      export DEV_HOST=$(gp url 8001)  # 设置环境变量
    init: npm install # 初始化命令
    command: npm start # 主命令

Gitpod 是一个基于云的开发环境平台，线上编程，可以让开发者通过浏览器快速获得一个配置好的开发环境，无需在本地安装任何工具或依赖。

核心特点:

  1. 即时开发环境 ：通过浏览器即可获得完整的开发环境
  2. 预配置环境 ：基于配置文件自动设置开发环境
  3. 协作功能 ：支持多人实时协作开发
  4. 与GitHub集成 ：可直接从GitHub仓库启动环境

文档站点处理

这里面跟文档处理相关的目录或文件有三个：

  • .dumi（文档）
  • .surgeignore（静态部署）
  • CNAME（域名指向设置）

作为一个组件库，文档相关的设置肯定是必须且重要的。

dumi

dumi 基于 React 的文档站点生成工具，它的主要特点包括：

  1. 核心功能：
    • 支持 React 组件文档的编写和预览
    • 支持 Markdown 文档的编写和预览
    • 支持 API 文档的自动生成
    • 支持多语言文档
  2. 典型应用场景：
    • 组件库文档
    • 博客文档
    • 技术文档
  3. 与 ant-design-tools 的关系：
    • 作为@ant-design/tools的底层引擎
    • 处理组件库的文档生成、发布等任务
    • 提供文档站点的构建能力
  4. 优势：
    • 配置简单（无需额外配置）
    • 文档编写灵活（支持 React 组件、Markdown 文档）
    • 文档预览高效（基于 React 组件）
    • 文档生成自动化（API 自动生成）
    • 多语言支持（支持国际化）
  5. 劣势：
    • 配置复杂（需要额外配置）
    • 文档编写复杂（需要掌握 React 组件、Markdown 文档）
    • 文档预览复杂（需要掌握 React 组件）
    • 文档生成复杂（需要掌握 React 组件、Markdown 文档）
    • 多语言支持复杂（需要掌握国际化）

.surgeignore

.surgeignore 文件用于配置 Surge 部署时需要忽略（不上传到 Surge 静态站点托管服务）的文件或目录。

在项目中， .surgeignore 文件内容为：

!.dumi*

这行配置的含义是：

  • !.dumi\* 表示 不要忽略 所有以 .dumi 开头的文件或文件夹（即这些文件/文件夹会被包含进 Surge 部署）。
  • ! 号在 ignore 规则中表示“反向”，即排除前面规则的忽略。 通常 .surgeignore 会用来排除某些构建产物、临时文件或源码目录，而 ! 前缀则用来确保某些特定文件/目录被包含进部署包。你的配置说明 .dumi 相关内容是部署所需的，不能被忽略。

Surge 是一个简单易用的静态网站托管服务，主要用于前端项目的快速部署和预览。

它的核心特点包括：

  • 通过命令行工具（surge CLI）一条命令即可将本地构建好的静态资源（如 HTML、CSS、JS 等）部署到 Surge 的云服务器上。
  • 部署后会自动生成一个可访问的自定义域名（如 your-project.surge.sh），方便团队成员或用户访问和预览。
  • 支持自定义域名绑定、HTTPS、基本的缓存和重定向配置等。
  • 免费套餐适合个人开发者和开源项目，付费套餐支持更多高级功能。

常见用法：

  1. 全局安装 Surge CLI： 
    npm install -g surge
  2. 在项目构建产物目录下执行： 
    surge
  3. 按提示输入邮箱、设置域名，即可完成部署。

Surge 适合用于前端项目的快速预览、演示和分享。

CNAME

CNAME 文件是一个文本文件，用于将一个域名指向另一个域名，是静态站点自定义域名绑定的关键配置文件。

CNAME 文件用于静态网站部署（如 GitHub Pages、Surge、Netlify 等）时，指定自定义域名。

项目中，CNAME 文件内容为：

ant.design

这表示：

  • 当你将该项目部署到静态网站托管服务时，服务会自动读取 CNAME 文件，将 ant.design 作为该站点的自定义域名进行绑定。
  • 这样访问者可以直接通过 https://ant.design 访问你的网站，而不是使用默认的托管子域名（如 xxx.github.io 或 xxx.surge.sh）。
  • 你需要在域名服务商处将 ant.design 的 DNS 解析指向对应的托管服务。

GitHub设置

这里面的GitHub的设置主要指的是.github文件夹。

.github 文件夹是 GitHub 项目的标准配置目录，主要用于存放 GitHub 特有的配置和工作流文件。项目中，这个文件夹包含以下重要配置：

  1. 核心配置文件 ：

    • CONTRIBUTING.md : 贡献指南，说明如何为项目做贡献
    • FUNDING.yml : 项目资助配置，显示在 GitHub 仓库顶部的赞助按钮
    • ISSUE_TEMPLATE.md : Issue 模板，规范问题报告格式

  2. 工作流配置 (在 workflows/ 目录中):

    • 自动化测试和构建流程
    • 站点部署配置（如将文档部署到 Surge）
    • 版本发布流程

  3. Issue 模板 (在 ISSUE_TEMPLATE/ 目录中):

    • 标准化的问题报告模板
    • Bug 报告、功能请求等分类模板

  4. 自动化流程 :

    • 使用 GitHub Actions 实现 CI/CD
    • 自动检查代码质量
    • 依赖更新管理（通过 dependabot.yml 配置）

测试相关

这里和测试相关的有jest、codecov；一个是执行测试的，一个是进行测试覆盖率处理的。

jest

这些是项目中针对不同测试场景的 Jest 配置文件：

  1. .jest.js - 主测试配置文件，包含基本配置和通用设置
  2. .jest.image.js - 专门用于图像快照测试的配置
  3. .jest.node.js - 用于 Node.js 环境测试的配置
  4. .jest.site.js - 用于网站相关测试的配置 它们都从 .jest 文件导入共享配置（ moduleNameMapper 和 transformIgnorePatterns ），然后根据各自测试环境扩展特定配置。
  5. jest-puppetee.config.js- 用于配置 Jest 与 Puppeteer 集成测试环境的文件。其主要作用是自定义 Puppeteer 启动浏览器时的参数

Puppeteer 是由 Google 开发的一个 Node.js 库，它提供了一个高级 API 用于通过编程方式控制 Chrome 或 Chromium 浏览器。你可以使用 Puppeteer 实现自动化网页操作，比如自动打开网页、点击按钮、填写表单、截图、生成 PDF、抓取数据等。

Jest 是一个开箱即用的 JavaScript 测试框架，主要用于前端项目的单元测试、集成测试和快照测试。

工作原理简述：

  1. 收集测试文件：Jest 根据配置（如testRegex、testMatch等）自动查找所有测试文件。
  2. 环境准备：根据配置（如setupFiles、testEnvironment），初始化测试运行环境（如 jsdom 或 node），并加载全局变量、polyfill 等。
  3. 文件转换：通过transform字段，Jest 会用 Babel、ts-jest 等预处理器将源码和测试代码转换为可执行的 JavaScript。
  4. 模块解析与 Mock：根据moduleNameMapper等配置，Jest 支持模块别名、样式文件 mock、自动模拟依赖等。
  5. 执行测试：Jest 会并发运行测试用例（受maxWorkers控制），每个测试文件在独立沙箱环境中执行，保证互不影响。
  6. 断言与快照：测试用例通过 expect 断言，支持快照测试（snapshot）自动比对 UI 变化。
  7. 结果输出与覆盖率：Jest 汇总测试结果，输出详细报告，并可根据collectCoverageFrom收集代码覆盖率。

核心优势：

  • 零配置即可运行，集成 Babel/TypeScript/React 等主流技术
  • 内置 Mock、快照、并发执行、覆盖率统计
  • 通过配置文件灵活扩展，适合大型前端项目

Jest 的底层原理是通过 Node.js 启动多个 worker 进程，利用沙箱机制隔离测试环境，结合 AST 转换和模块代理，实现高效、可靠的自动化测试流程。

codecov

codecov.yml 文件是用于配置 Codecov 代码覆盖率服务的项目级配置文件。

在项目中， codecov.yml 内容如下：

coverage:
  status:
    project: #add everything under here, more options at https://docs.codecov.com/docs/
    commit-status
      default:
        target: 100%
        threshold: 0%

解释：

  • coverage: 顶层字段，表示整体代码覆盖率相关配置。

  • status: 配置覆盖率状态检查。

  • project: 针对整个项目的覆盖率目标。

  • default: 默认分支或所有分支的覆盖率要求。

    • target: 100% 要求项目的代码覆盖率必须达到 100%。
    • threshold: 0% 表示允许的覆盖率下降阈值为 0%，即覆盖率不能有任何下降。 作用：

  • 当你在 CI（如 GitHub Actions）中集成 Codecov 时，每次提交或 PR 都会自动检测代码覆盖率。

  • 如果覆盖率低于 100% 或有下降，CI 检查会失败，提醒开发者补充测试。

  • 这样可以保证项目始终保持高质量的测试覆盖率。

Codecov 代码覆盖率服务的整体工作流程如下：

  1. 编写测试用例 ：开发者在项目中为各个功能模块编写自动化测试用例，通常放在 components/**tests** 、 tests/ 等目录。

  2. 运行测试并收集覆盖率 ：在本地或 CI（如 GitHub Actions）环境中执行测试命令（如 npm test 或 yarn test ），测试框架（如 Jest）会自动收集哪些代码被实际执行，并生成覆盖率报告（如 coverage/lcov.info ）。

  3. 上传覆盖率报告到 Codecov ：CI 流程中集成了 Codecov 上传脚本（如 bash <(curl -s https://codecov.io/bash) ），会自动将覆盖率报告上传到 Codecov 平台。

  4. Codecov 分析并比对覆盖率 ：Codecov 读取上传的报告，结合项目根目录下的 codecov.yml 配置，分析本次提交或 PR 的代码覆盖率。

  5. 状态检查与反馈 ：如果覆盖率低于 codecov.yml 设定的目标（如 100%），或者覆盖率有下降，Codecov 会在 PR 或 CI 检查中给出警告或失败提示，开发者可以在 Codecov 网站或 PR 页面查看详细的覆盖率报告和未覆盖的代码行。

  6. 持续改进 ：开发者根据反馈补充测试，提升覆盖率，保证项目质量。 总结 ：整个流程实现了自动化检测和反馈，帮助团队持续保持高测试覆盖率，及时发现未被测试的代码，提升代码可靠性和可维护性。

    执行测试命令时，代码覆盖率的收集并不是 Codecov 直接完成的，而是由测试工具（如 Jest）和覆盖率工具（如 istanbul、nyc）负责生成覆盖率报告。Codecov 只是负责读取和上传这些报告。

git管理

这里的git管理相关的文件是：husky、lint-staged，都是用来对git提交进行预处理的，这里的husky就不赘述了，主要讲lint-staged

.lintstagedrc.json

.lintstagedrc.json 是 lint-staged 的配置文件，用于在 Git 暂存区（staged）文件提交前自动执行代码检查和格式化命令。

具体配置解释如下：

{
  "*.{ts,tsx,js,jsx,css,mjs,json}": ["biome check --write --no-errors-on-unmatched", "eslint"],
  "*.{md,yml}": ["prettier --ignore-unknown --write"]
}
  • *.{ts,tsx,js,jsx,css,mjs,json}：匹配所有 TypeScript、JavaScript、CSS、MJS、JSON 文件，对这些文件依次执行：
    1. biome check --write --no-errors-on-unmatched：用 Biome 工具自动修复和格式化代码。
    2. eslint：用 ESLint 进行代码规范检查。
  • *.{md,yml}：匹配所有 Markdown 和 YAML 文件，执行：
    1. prettier --ignore-unknown --write：用 Prettier 自动格式化。

作用：保证每次 git commit 前，所有被暂存的代码和文档都经过自动格式化和规范检查，提高代码质量和一致性。

通常会配合 .husky/pre-commit 钩子，在每次 git commit 前自动运行 lint-staged 检查和格式化暂存区的文件，保证提交代码的质量和风格一致。

代码约束

项目中跟这个主题相关的文件、目录有：

  • .lintstagedrc.json
  • .prettierignore
  • .prettierrc
  • biome.json

前面几个都很熟悉，这里主要讲biome。

biome.json

biome.json 是 Biome 工具的配置文件，Biome 是一个现代化的 JavaScript/TypeScript 工具链，集成了代码格式化（Formatter）、代码检查（Linter）等功能。以下是文件内容的主要配置解析：

  1. 文件忽略规则 (files.ignore):

    • 指定了需要忽略的文件和目录，如构建输出目录（dist/）、临时文件（.dumi/tmp*）、node_modules 等。

  2. 格式化配置 (formatter):

    • 启用格式化功能
    • 使用空格缩进（indentStyle: "space"）
    • 缩进宽度为 2 个空格
    • 单引号作为字符串引号（quoteStyle: "single"）

  3. 代码检查规则 (linter.rules):

    • 关闭了部分严格的规则，如：
      • noExplicitAny: 允许使用 any 类型
      • noArrayIndexKey: 允许在 React 组件中使用数组索引作为 key
      • useKeyWithClickEvents: 不强制要求为点击事件添加键盘事件支持

  4. 特定文件覆盖规则 (overrides):

    • 对测试文件（*.test.ts）、脚本文件和 demo 文件放宽了部分规则限制

该配置文件主要用于统一项目的代码风格和质量标准，同时根据项目特点（如组件库）进行了合理的规则定制。

其实这里有一个疑问，为什么已经有了Biome，它既能做eslint的事情，又能做prettier的事情，那么为什么还要使用eslint和prettier呢？

  • 历史兼容性：许多大型项目在引入 Biome 前，已经有大量基于 Prettier 和 ESLint 的配置、插件和规则，直接迁移成本较高。
  • 生态兼容：部分社区插件、定制规则、CI 流程等目前只支持 ESLint/Prettier，Biome 还未完全兼容所有场景。
  • 渐进迁移：项目可能正处于从 Prettier/ESLint 逐步迁移到 Biome 的过渡阶段，三者并存可以保证新旧工具链都能正常工作，逐步替换和验证。
  • 功能补充：Biome 虽然功能强大，但某些细分检查或格式化细节，Prettier/ESLint 仍有独特优势，团队可能根据实际需求灵活选择。

Markdown格式检查

这个主题下相关的文件为：remarkrc.js，主要是对md语法进行修正，类似于eslint的功能。

remarkrc.js

.remarkrc.js 是 remark（一个 Markdown 语法检查和格式化工具）的配置文件，采用 CommonJS 导出方式。配置内容如下：

const config = {
  plugins: [
    'remark-preset-lint-recommended',
    ['remark-lint-no-undefined-references', { allow: [' ', /RFC/] }],
  ],
};

module.exports = config;
  • plugins 字段用于配置 remark 插件：
    • remark-preset-lint-recommended ：官方推荐的 Markdown 语法检查规则集合，帮助规范文档格式。
    • remark-lint-no-undefined-references ：检查文档中引用的链接或锚点是否未定义， allow 选项允许空字符串和匹配 /RFC/ 的引用不报错。 整体作用是保证 Markdown 文档格式规范、引用有效，提升文档质量。

remark 是一个 Markdown 生态的核心工具，它的本质是将 Markdown 解析为抽象语法树（AST），然后可以通过插件对 AST 进行各种处理。

remark 的插件体系非常丰富，既可以用来“转译”Markdown（如转为 HTML、MDX 等），也可以用来“检查和格式化”Markdown（如 lint、自动修复、风格统一等）。

在该项目的 .remarkrc.js 配置中，remark 主要作为 Markdown 的 lint 工具使用，通过插件对 Markdown 语法和引用进行检查和规范化。

打包工具

该项目的打包工具，目前从目录和文件内容看主要有三个：

这里就介绍gulp和mako，webpack大家都熟悉就不介绍了

gulp和ant-design-tools

Gulp 是一个基于 Node.js 的前端构建工具，主要特点包括：

  1. 核心功能：

    • 自动化任务运行（如编译、压缩、测试等）
    • 基于流的文件处理（高效内存操作）
    • 支持插件系统（2000+官方/社区插件）

  2. 典型应用场景：

    gulp.task('scripts', () => {
  return gulp.src('src/js/*.js')
    .pipe(concat('bundle.js'))
    .pipe(uglify())
    .pipe(gulp.dest('dist/js'));
});

  3. 与 ant-design-tools 的关系：

    • 作为@ant-design/tools的底层引擎
    • 处理组件库的编译、打包等任务
    • 提供任务编排能力（串行/并行执行）

  4. 优势：

    • 配置优于代码（简单直观）
    • 高性能（利用 Node.js 流）
    • 生态丰富（支持 Sass/Less/TypeScript 等）

mako.config.json

mako.config.json 是用于配置 Mako 构建工具的文件，主要用于优化和定制项目的打包、构建行为。文件中的各项配置说明如下：

  • optimization：优化相关设置
    • skipModules：是否跳过模块优化，false 表示不跳过。
    • concatenateModules：是否启用模块合并优化，false 表示不启用。
  • codeSplitting：代码分割策略
    • strategy：分割策略为 auto，即自动根据依赖关系进行代码分割。
  • watch：监听相关配置
    • _nodeModulesRegexes：指定监听 node_modules 下哪些包的变更，这里是以 rc- 开头的包。
  • hmr：是否启用热模块替换（Hot Module Replacement），false 表示不启用。
  • devtool：是否生成 source map，false 表示不生成。
  • experimental：实验性功能
    • magicComment：启用 magic comment 功能，true 表示开启。

整体来说，这个配置文件用于控制 Mako 构建工具的优化、代码分割、监听、热更新等行为，帮助提升项目的构建效率和灵活性。

在当前项目结构和配置，Mako 主要负责打包 components 目录下的所有组件模块（如 button、table、form 等），以及相关的工具、样式、主题等内容。

具体说明如下：

  • components/ 目录包含了 Ant Design 的全部 UI 组件源码，每个子目录对应一个独立的组件模块。
  • Mako 会根据入口配置（通常为 components/index.ts 或类似文件）将这些组件源码进行打包、优化和代码分割，最终输出到 lib/、es/ 等目录，供 npm 包发布或项目引用。
  • 配置中的 watch._nodeModulesRegexes 指定了对 node_modules 下以 rc- 开头的依赖包进行监听，确保这些依赖变更时也能自动重新打包。
  • 除了组件源码，Mako 还会处理样式文件、主题配置、工具函数等相关内容，保证整个组件库可以被完整打包和发布。

最后

这篇文章主要讨论了，ant design项目中涉及到的文件、目录，挖掘背后的工程化设置，文章比较长，主要是结合实际代码查看，不需要从头看到尾。

可以看到这个组件库在各个方面都进行了设置和管理，是非常值得学习和借鉴的。

ok，这就是这篇文章的内容了，我是李仲轩，下期再见👋！

avatar
文章
阅读
粉丝