Redux Toolkit 仓库贡献指南：从环境搭建、构建测试到提交 Pull Request 的完整工作流

本篇指南以仓库根目录的 CONTRIBUTING.md 为骨架，面向希望向 Redux Toolkit 提交代码、修复文档或补充示例的开发者。你将完整掌握该仓库的参与方式、pnpm 工作区环境搭建、pnpm build / pnpm test 等核心命令的用法与底层实现，以及提交 Pull Request（PR）前必须完成的检查项（包括 API 报告更新）。读完即可按官方流程把第一个贡献安全地合入主分支。

参与 Redux Toolkit 的三种主要方式

社区贡献并不只限于写代码。官方明确欢迎以下三类贡献：

1. 报告 Bug 与提出改进：使用 Issue 跟踪器记录 Redux Toolkit 本身、示例（examples）和文档（docs）中的问题，也可以发起关于架构、内部实现与理论设计的讨论。
2. 编写或更新文档：如果你擅长文档写作，可以针对某个功能或实现补充 docs 中的内容；文档的构建与预览由 website（Docusaurus 站点）承载。
3. 补充第三方集成示例：仓库的 examples 目录下维护了 GraphQL、React 等各类集成样例，帮助用户理解如何把 Redux Toolkit 与特定框架/库结合使用。

无论选择哪条路径，都请先遵守 CODE_OF_CONDUCT.md 中的行为准则。

报告 Issue 与提问的正确姿势

在打开 Issue 之前，务必先搜索 [Issue 跟踪器] 确认问题是否已被报告。对于一般性问题和具体实现问题，官方要求优先到 Stack Overflow（带 redux-toolkit 标签）提问，而不是直接开 Issue——理由是 Stack Overflow 能更好地让热门问题保持可见，而 GitHub 上的好答案容易遗失或过时。若提问被关闭或数日无人回复，再考虑发起 discussion 或加入 Reactiflux Discord 的 #redux 频道。

官方特别强调「帮助我们帮助你」（Help Us Help You），这包含一组对提问者的硬性要求：

• 代码与问题描述要结构化、易读，善用语法高亮、缩进与分段；
• 提供相关库的版本号（例如 @reduxjs/toolkit、react-redux 的版本）；
• 提供一个可运行的、最小化的复现项目，并把所有依赖声明在 package.json 中，使任何人执行 npm install && npm start 即可复现问题。

这与仓库的自我验证文化一致：测试环境（见下文）已内置 MSW（Mock Service Worker）等工具，复现脚本也因此被社区普遍接受。

本地环境搭建：Fork、Clone 与安装依赖

Fork 并克隆仓库

官方建议通过 GitHub UI 的 Fork 按钮创建自己的副本（仓库 CI 已开启 forked builds，你可以在 fork 的分支上直接看到构建状态），然后克隆：

git clone https://github.com/your-username/redux-toolkit.git

若需直接克隆本镜像仓库，可使用 git clone https://gitcode.com/gh_mirrors/re/redux-toolkit 后按相同流程操作。

安装依赖：pnpm 与 Corepack

仓库采用 pnpm workspace 单仓（monorepo） 结构，根目录 package.json 中声明了 "packageManager": "pnpm@11.23.0"。这意味着 pnpm 版本被锁定在根配置里，Node 自带的 Corepack 会自动读取该字段并使用正确版本，无需全局安装 pnpm。进入仓库根目录执行：

$ cd redux-toolkit
$ pnpm install

安装配置集中存放在 pnpm-workspace.yaml，其中有几处值得注意的工程决策：

• 工作区包含 packages/*、docs、website、website/plugins/remark-typescript-tools、部分 examples 与 examples/type-portability/*；
• nodeLinker: hoisted 复现扁平依赖布局；
• autoInstallPeers: false 关闭 pnpm 默认的 peer 自动安装，避免拉入仓库从未拥有的 Next.js、Jest 30 等无关依赖；
• linkWorkspacePackages: false 确保 @rtk-query/codegen-openapi 从 registry 获取已发布的 RTK 1.x，而不是本地工作区里的 2.x。

这些细节解释了为什么 pnpm install 是唯一被官方认可的安装方式——直接使用 npm/yarn 会破坏工作区布局。

构建全部包：pnpm build

构建命令很简单：

pnpm build

根 package.json 将其映射为 pnpm build:packages，即通过 pnpm --recursive --filter "@reduxjs/*" --filter "@rtk-query/*" run build 递归构建所有发布包。目前工作区内的发布包包括：

• @reduxjs/toolkit（packages/toolkit/package.json，当前版本 2.12.0）——核心包；
• @reduxjs/rtk-codemods（packages/rtk-codemods/package.json）——基于 jscodeshift 的重构脚本工具包；
• @rtk-query/codegen-openapi（packages/rtk-query-codegen-openapi/package.json）——从 OpenAPI 生成 RTK Query API 的 CLI；
• @rtk-query/graphql-request-base-query（packages/rtk-query-graphql-request-base-query/package.json）——基于 graphql-request 的 baseQuery。

以核心包为例，其构建脚本定义在 packages/toolkit/package.json：

"build": "pnpm clean && pnpm run-build && tsx scripts/fixUniqueSymbolExports.mts && tsx scripts/stripSourcemapFileField.mts",
"run-build": "tsdown --config=./tsdown.config.mts --config-loader unrun"

run-build 使用 tsdown/Rolldown 执行打包，具体产物矩阵由 packages/toolkit/tsdown.config.mts 定义：核心 ESM（redux-toolkit.modern.mjs）、CJS 开发版/生产压缩版、浏览器版（platform: 'browser' 且 define: { process: 'undefined' }）、面向 es2017 的 legacy ESM，以及 react、query、query/react 三个嵌套入口（如 rtk-query-react.*）。构建过程中还会执行两个后处理脚本：

• scripts/fixUniqueSymbolExports.mts：修复导出符号问题；
• scripts/stripSourcemapFileField.mts：剥离产物中的 sourcemap 文件字段；
• 同时 scripts/mangleErrors.mts 作为 Babel/Rolldown 插件将错误消息替换为错误码（配合根目录 errors.json 使用），从而显著压缩产物体积。

如果你只想构建并验证打包产物而不做后处理，也可以运行包级脚本 pnpm --filter @reduxjs/toolkit build-only。

运行测试：pnpm test 与 watch 模式

测试同样支持全量运行与增量监听两种方式：

pnpm test

pnpm --filter @reduxjs/toolkit test:watch

根脚本 test 映射为 test:packages，即递归运行所有包的测试。核心包的测试配置位于 packages/toolkit/vitest.config.mts：

test: {
  globals: true,
  environment: 'jsdom',
  setupFiles: ['./vitest.setup.ts'],
  include: ['./src/**/*.(spec|test).[jt]s?(x)'],
  server: { deps: { inline: ['redux', '@reduxjs/toolkit'] } },
  unstubEnvs: true,
}

几个值得注意的测试事实：

• 测试即类型测试：test 脚本为 vitest --typecheck --run，即每次运行都会同时执行 .test-d.ts 类型级测试（如 packages/toolkit/src/tests/configureStore.test-d.ts）与运行时测试，确保公开 API 的类型签名不被破坏；
• 全局 MSW 网络模拟：packages/toolkit/vitest.setup.ts 用 node-fetch 桩掉全局 fetch，并启动 packages/toolkit/src/query/tests/mocks/server 的 MSW 服务器，未处理请求直接报错——这就是为什么测试涉及网络层时无需真实后端；
• 测试文件分布：核心逻辑测试集中在 packages/toolkit/src/tests（含 createSlice.test.ts、createAsyncThunk.test.ts、configureStore.test.ts 等），RTK Query 测试在 packages/toolkit/src/query/tests，Entity Adapter 与 Listener Middleware 也有各自的 tests 子目录。

提交 PR 前请确保 所有测试通过且无 lint 错误。仓库的 lint 与格式化工具是 oxlint 与 oxfmt（根 package.json 中 lint、format、format:check 脚本）。

标准 Git 工作流：从分支到 Pull Request

官方推荐的提交流程如下：

1. 在 Issue 跟踪器新建一个 Issue（记录 Bug 或改进点）；
2. Fork 仓库；
3. 基于 master 分支创建新的功能分支；
4. 确保所有测试通过、无 lint 错误；
5. 提交 Pull Request，并在描述中引用其解决的 Issue 编号；
6. 若改动了对外暴露的类型，还需本地构建并更新 API 报告文件；
7. 尽量保持 PR 范围聚焦，避免混入无关提交。

提交后维护者会尽快回复，并可能提出修改或改进建议。

关键检查点：更新 API 报告文件

CONTRIBUTING.md 特别强调：如果你更改了外部可见（external-facing）的类型，必须在本地构建项目，并把更新后的 API 报告文件 etc/redux-toolkit.api.md 一并提交到 PR 中。该文件实际位于 packages/toolkit/etc/redux-toolkit.api.md。

API 报告由 Microsoft API Extractor 生成，配置见 packages/toolkit/api-extractor.json：它以 dist/index.d.ts 为入口分析导出符号，apiReport.enabled: true 且 reportFileName: "redux-toolkit.api.md"、reportFolder: "<projectFolder>/etc/"。仓库同时为 RTK Query 维护了 rtk-query.api.md 与 rtk-query-react.api.md（见 packages/toolkit/etc）。由于该文件被 Git 跟踪，任何公开 API 的增删改都会在 diff 中显式呈现，从而把「破坏性变更是否被接受」变成一次显式的代码评审议题。

文档与示例贡献的额外说明

• 文档仓库：docs 与 website 目录均属工作区成员。本地预览文档站点可运行根脚本 pnpm dev:docs（即 pnpm --filter website run start），构建站点用 pnpm build:docs。文档内容以 .md / .mdx 编写，例如 docs/introduction/getting-started.md、docs/usage/migrating-rtk-2.md 是快速入门与 v2 迁移指南。
• 示例仓库：第三方集成示例放在 examples 下，涵盖 React Query、Vite、Next.js、Expo、React Native 等；examples/type-portability 下的 bundler / nodenext-cjs / nodenext-esm 三个子项目用于验证类型在不同模块解析策略下的可移植性。
• 包内技能（skills）：@reduxjs/toolkit 发布包还携带了 skills/ 目录（调试、迁移、状态建模等操作指南），若你的改动涉及这些内容，同样需要保持更新。

常见问题与注意事项速查

场景	官方要求 / 说明
提问优先渠道	Stack Overflow（redux-toolkit 标签）→ 讨论区 / Reactiflux #redux
安装依赖	pnpm install，依赖 Corepack 自动读取根 package.json 的 packageManager 字段
全量构建	pnpm build（递归构建所有发布包）
全量测试	pnpm test（含 --typecheck 类型测试与 MSW 网络模拟）
增量测试	pnpm --filter @reduxjs/toolkit test:watch
分支基线	从 master 创建功能分支
提交前提	测试全绿、无 lint 错误、PR 聚焦单一主题
类型改动	本地构建并提交更新后的 packages/toolkit/etc/redux-toolkit.api.md

遵循这套流程，你的贡献将与其他社区成员的改动一样，经过统一的构建、类型检查、lint 与 API 变更评审后进入主分支。感谢你参与 Redux Toolkit 的开发！