企业官网建设流程全解析

• 前端

本篇指南基于 CONTRIBUTING.md 整理，面向准备为 rematch（The Redux Framework）提交代码或文档的开发者。文中将完整覆盖官方贡献流程：如何搭建基于 Lerna + Yarn Workspaces 的 monorepo 开发环境、必须遵守的语义化提交规范、build/test/lint 三重验证要求、沙盒示例应用的使用方法，以及 Docusaurus 文档站点的本地开发与检查方式，帮助你在提交第一个 Pull Request 前把工程链路跑通。

贡献理念：让每个人都能迈出第一步

rematch 官方在 CONTRIBUTING.md 开篇明确了项目演进哲学：库的演化不应被任何一个人的时间所阻塞，因此项目鼓励大量“浅层贡献者”（shallow contributors）参与，以缓解“项目需要更新却没有人有权力去做”的困境。围绕这一理念，官方提供了两类机制：

• good first step issues：这类 issue 通常是非关键的、边界清晰的问题，成熟贡献者会刻意避开它们，为新贡献者留出空间，使第一次 PR 不会“踩到别人的地盘”；
• 讨论渠道分工：所有技术讨论应留在 GitHub Issues 中（具体 PR 讨论、新 API 想法等都属于此类），其他非技术讨论则放在官方 Discord 社区。官方还说明，若存在无法在公开 issue 中讨论的问题，维护者 Sergio Moreno 的 GitHub 主页上有可联系的邮箱。

需要特别注意的是，所有 rematch 仓库均受 代码行为准则（Code of Conduct） 约束，贡献前应先阅读该文件，发现违规行为时也应协助执行。

环境搭建：为什么必须使用 yarn

rematch 是一个典型的 monorepo，根目录 package.json 通过workspaces字段声明了工作区成员：

"workspaces": [ "packages/*", "website", "examples/all-plugins-react-ts", "examples/hooks-react-ts", "examples/count-react-ts" ]

从源码结构看，packages/*对应 core、immer、loading、persist、select、typed-state、updated 等核心包与插件包，website是 Docusaurus 文档站点（内部包名为rematch-docs，见 website/package.json），三个examples/*则是 TypeScript 沙盒示例应用。monorepo 的编排由 lerna.json 中的"useWorkspaces": true与"npmClient": "yarn"配置完成——这也是 CONTRIBUTING.md 反复强调“永远使用 yarn，npm install 不会工作”的原因：依赖安装与联调依赖 yarn workspaces 的符号链接机制，npm 无法正确解析工作区内的本地包引用。

官方给出的环境搭建步骤非常直接：

# 1. 安装全部依赖（必须使用 yarn） yarn install # 2. 首次构建，用于生成类型声明等产物 yarn build # 3. 启动 live-reloading 测试套件（等价于 lerna run test --stream -- --watch） yarn watch

之后直接在packages/core/src/、packages/loading/src/等包内目录（CONTRIBUTING.md 原文写作packages/core|loading|any-plugin/src/，对应当前仓库的packages/<包名>/src/结构）中编辑代码即可。

几点与仓库实际配置对应的说明：

• 根脚本中build实际执行lerna run build --ignore rematch-docs，即对所有包执行各自的构建脚本。以 packages/core/package.json 为例，@rematch/core的 build 使用dts build --format cjs,esm,umd同时产出 CommonJS、ESM 与 UMD 三种格式及类型声明；
• postinstall钩子会执行husky install，安装 Git hooks；lint-staged配置会在提交前对packages/**/*.{ts,tsx,jsx,js,json,md,mdx}执行 ESLint 检查（见 package.json 中lint-staged字段）；
• 全局测试的 Jest 配置非常轻量：jest.config.js 仅声明了setupFiles: ['<rootDir>/testSetup.js']，而 testsetup.js 的作用是在测试运行期间将unhandledRejection直接抛出为异常，保证异步错误不会在测试中被静默吞掉——这对编写 effects 相关测试尤其重要。

此外，官方还提供 Gitpod 一键在线开发环境：点击“Open in Gitpod”按钮即可自动完成仓库克隆、依赖安装，并运行yarn watch与yarn docs，免去本地环境准备。

代码贡献的完整工作流

CONTRIBUTING.md 将一次代码贡献总结为 12 步，以下是完整流程（其中分支与提交环节补充了与仓库配置对应的细节）：

1. 选定 issue 或功能：确认没有其他人正在处理，避免重复劳动；
2. Fork 后克隆：git clone https://github.com/YOUR_USERNAME/rematch.git；
3. 创建有意义的分支：git checkout -b fix-something；
4. 安装依赖：在项目根目录运行yarn install（再次强调必须使用 yarn，因为 monorepo 依赖 yarn workspaces）；
5. 修改并暂存提交：git add与git commit；
6. 提交信息必须语义化：遵循 Conventional Commits 规范。这一要求并非纸面规定——根 package.json 中集成了@commitlint/cli与@commitlint/config-conventional（"commitlint": { "extends": ["@commitlint/config-conventional"] }），不符合规范的提交信息会被自动拦截；
7. 验证测试通过：依次运行yarn build、yarn test、yarn lint。对照根脚本可以看到：test执行lerna run test（每个包内部为dts test），lint执行lerna run lint；
8. 推送分支：git push -u origin your-branch-name；
9. 向上游 rematch 仓库提交 Pull Request；
10. 填写描述性的标题并简要说明变更内容；
11. 等待维护者 review，按建议修改直至合入；
12. 跳一支庆祝的舞。

如何验证你的修改

为了让开发流程更顺畅，仓库内置了自动引用本地版本 rematch 的沙盒 React 应用。CONTRIBUTING.md 指出：当你在packages/.../core/src/下做出任何修改，沙盒应用会自动反映这些变更（重新加载 dist 只需运行yarn build）。从workspaces配置看，实际参与联动的沙盒是 examples/all-plugins-react-ts、examples/hooks-react-ts 与 examples/count-react-ts 三个 TypeScript 示例，其中 all-plugins-react-ts 同时演示了带 Hooks 与不带 Hooks 的两种用法（src/AppWithHooks.tsx与src/AppWithoutHooks.tsx），并覆盖了 cart、players、settings 等 model（见 examples/all-plugins-react-ts/src/models）。仓库中还有 count-react、loading-react、persist-react、select-react、updated-react、multi-react、nextjs-blog、gatsby-example 等更多示例（见 examples/README.md），可以作为修改后手动验证行为的表现参考。

文档贡献流程

文档站点是仓库中的独立工作区website，基于 Docusaurus 2.0（beta），内容源在 docs/ 目录（含 api-reference、plugins、migrating、recipes 等章节），博客文章位于 blog/。官方给出的文档贡献步骤为：

# 1. 项目根目录安装依赖 yarn install # 2. 启动文档站（等价于 lerna run start --scope rematch-docs --stream） yarn start:docs # 3. 自由编辑 docs/ 下的文档 # 4. 检查 prettier 与 eslint（等价于 lerna run lint --scope rematch-docs --stream） yarn lint:docs # 5. git add、git commit 并推送到新分支，提交 PR

对照 website/package.json 可以看到文档站的 lint 由 ESLint（**/*.{js,jsx,ts,tsx}）执行，Markdown 则由 Prettier 管理（prettier-docs脚本对**/*.md写入格式化），lint-staged会在提交前对*.{js,jsx,ts,tsx}执行eslint --fix+prettier --write、对*.{md,mdx}执行prettier --write。此外文档站还使用docusaurus-preset-shiki-twoslash提供代码高亮与 TypeScript 实时检查，并在website/src/plugins/remark-npm2yarn.js中用 remark 插件把示例里的 npm 命令自动转成 yarn——这与全文强调“只用 yarn”的约定是一脉相承的。

质量护栏：从提交到发布的工程约束

CONTRIBUTING.md 没有单独展开发布章节，但从仓库配置可以确认若干与贡献质量直接相关的约束，便于在开发时就对齐标准：

• 体积预算：根 package.json 配置了size-limit，对各包 UMD 产物设定上限（如@rematch/core生产包不超过 2 kB、persist 不超过 200 B、select 不超过 500 B 等），提交体积显著增加的代码前可以运行yarn size-build自查；
• 发布分支限制：lerna.json 中publish.allowBranch只允许main、master、next三个分支发布，且 CHANGELOG、examples、Markdown 等文件变更不会触发版本变动；
• 版本管理：根脚本version:latest*/release:latest系列使用lerna version/publish配合 conventional commits 自动完成版本推导与 GitHub Release 创建。

以上机制意味着：普通贡献者只需关注yarn install→ 修改 →yarn build && yarn test && yarn lint→ 规范提交 → PR 这条主线，版本与发布由维护者统一处理。

小结

rematch 的贡献链路可以概括为三句话：

1. 环境：monorepo 基于 Lerna + Yarn Workspaces，永远用yarn install起步，首次yarn build生成类型，yarn watch进入热重载测试循环；
2. 代码：遵循 Conventional Commits（commitlint 强制），提交前通过yarn build、yarn test、yarn lint三重验证，可用examples/下的沙盒应用直观验证行为；
3. 文档：yarn start:docs本地预览 Docusaurus 站点，yarn lint:docs检查格式后提交 PR。

按 CONTRIBUTING.md 的表述，官方为新手特意预留了边界清晰的 good first step issues 和完整的在线开发环境，第一次贡献的重点是把上述链路完整跑通，再逐步参与更深的功能设计讨论（GitHub issues）与社区交流（Discord）。

• 前端