Redux 安装指南：redux 核心、Redux Toolkit 与配套生态的完整接入方式

本文以 Redux 官方文档中的 Installation 页面为主体，完整覆盖 Redux 核心包、Redux Toolkit、React-Redux 绑定库和开发工具扩展的安装方式，并结合本仓库的 package.json 导出配置、tsup 构建脚本与 examples 示例工程，说明每个安装选项背后的产物格式、适用场景和浏览器直用方案，帮助你在不同构建工具下正确引入 Redux。

安装 Redux Toolkit（官方推荐入口）

官方文档的第一建议是：大多数应用应从 Redux Toolkit（@reduxjs/toolkit）开始，而不是裸用 Redux 核心。Toolkit 在 Redux 核心之上封装了构建 Redux 应用所需的关键能力，包含 Redux Thunk（异步逻辑）和 Reselect（派生数据选择器）等关键包，也包含 configureStore、createSlice 等官方推荐 API（参见 docs/redux-toolkit/overview.md）。

标准安装命令如下：

# NPM
npm install @reduxjs/toolkit

# Yarn
yarn add @reduxjs/toolkit

本仓库内的官方示例工程也印证了这一推荐路径。以 counter 示例为例，其 examples/counter/package.json 的依赖正是 @reduxjs/toolkit（^2.1.0）+ react-redux（^9.1.0），而 store 的创建直接使用 Toolkit 的 configureStore（见 examples/counter/src/app/store.js）：

import { configureStore } from '@reduxjs/toolkit'
import counterReducer from '../features/counter/counterSlice'

export const store = configureStore({
  reducer: {
    counter: counterReducer
  }
})

这个组合与 Redux 核心的现状一致：在 src/createStore.ts 中，createStore 已被标记为 @deprecated，文档注释明确建议改用 @reduxjs/toolkit 的 configureStore——后者"提供了简化的配置选项和良好默认值"，并且可以静默跳过弃用警告的旧 API 是 legacy_createStore。因此，新项目的默认安装选择是 Toolkit，而非 redux 包本身。

配套包：React-Redux 绑定

如果应用使用 React，还需要安装 Redux 与 React 的绑定层 react-redux：

npm install react-redux

官方文档在此处特别提示了一个实践要点：与 Redux 核心不同，Redux 生态中的许多包并不提供 UMD 构建，因此推荐搭配 Vite、Webpack 等模块打包器使用，以获得最舒适的开发体验。这也是为什么官方安装方式始终是包管理器 + 打包器组合，而不是在 HTML 中直接引用 CDN 脚本。

开发工具扩展（DevTools Extension）

安装完核心依赖后，开发体验的关键一环是浏览器扩展。官方文档指出：Redux Toolkit 的 configureStore 会自动配置 Redux DevTools 集成，无需手动接线，开发者只需安装对应的浏览器扩展即可查看 store 状态和 action：

• Redux DevTools Extension：Chrome 版与 Firefox 版均可在浏览器扩展商店安装；
• React DevTools Extension：使用 React 的项目建议同时安装，用于检查组件树与 hook 状态。

本仓库中也有大量 DevTools 相关的截图佐证这一工作流，例如 website/static/img/tutorials/essentials/devtools-rtkq-cache.png 展示了 RTK Query 缓存在 DevTools 中的呈现方式。需要注意的是，DevTools 集成"开箱即用"的前提正是通过 Toolkit 的 configureStore 创建 store；如果直接使用 redux 核心的 createStore，则需要自行通过 enhancer 接入 DevTools。

使用官方模板创建 React Redux 应用

官方文档推荐的"从零起步"方式是使用官方模板，而不是手动装配依赖。两个主流选择：

# 方式一：Vite + 官方 Redux+TS 模板
# （使用 `degit` 工具克隆并解压模板）
npx degit reduxjs/redux-templates/packages/vite-template-redux my-app

# 方式二：Next.js 的 with-redux 官方示例模板
npx create-next-app --example with-redux my-app

两个模板的共同点（原文档明确说明）：

• 已针对各自构建工具正确配置好 Redux Toolkit 和 React-Redux；
• 附带一个小型示例应用，演示 Redux Toolkit 的若干特性用法。

另外，官方文档也说明：目前暂无官方的 React Native 模板，社区中为标准 React Native 和 Expo 提供了可用的第三方 TypeScript 模板（可在文档页查阅推荐清单）。本仓库 examples/ 目录下的多个示例（counter、todos、real-world 等，描述见 docs/introduction/Examples.md）也可以作为不同构建方式下依赖组织方式的参考。

安装 Redux 核心包（redux）

如果需要单独安装 Redux 核心库（典型场景：学习底层原理、或库/非 React 环境中直接管理状态）：

# NPM
npm install redux

# Yarn
yarn add redux

从本仓库 package.json 可以确认当前发布的核心包为 redux@5.0.1，MIT 协议。该包同时提供了多种产物形态，exports 字段的解析规则如下：

入口	文件	适用场景
main	dist/cjs/redux.cjs	CommonJS（Node、传统打包配置）
module	dist/redux.legacy-esm.js	指向 .js 扩展名的 ESM 文件，用于兼容 Webpack 4
exports.import	dist/redux.mjs	标准 ESM，内嵌 process.env.NODE_ENV 检查
exports.types	dist/redux.d.mts	TypeScript 类型声明

这些产物由 tsup.config.ts 定义的四组构建任务生成：标准 ESM（.mjs）、Webpack 4 兼容的 legacy ESM（.js，target 为 es2017）、浏览器直用版 redux.browser.mjs（production 内联、已压缩的 ESM），以及 CJS。构建入口统一为 src/index.ts，它导出了全部核心 API：createStore、legacy_createStore、combineReducers、bindActionCreators、applyMiddleware、compose，以及工具函数 isAction、isPlainObject、ActionTypes 和完整类型定义。

两个对安装行为有实际影响的细节：

• "sideEffects": false 声明在 package.json 中，意味着打包器可以对 Redux 模块安全地做 tree-shaking；
• 构建管线还包含一个错误信息混淆插件（scripts/mangleErrors.mts），把冗长错误文案替换为错误码以减小体积，配合 src/utils/formatProdErrorMessage.ts 在运行时还原可读信息——这解释了为什么生产环境中看到的错误提示较为简短。

不使用打包器：浏览器 ESM 直用

官方文档明确说明：redux 包包含预编译的 ESM 构建，可以通过 <script type="module"> 标签直接在浏览器中使用，也可以下载该文件或将包管理器指向 CDN 上的对应文件。

本仓库提供了一个可直接运行的零依赖演示：examples/counter-vanilla/index.html 通过 ES module import 引入浏览器构建版 redux.browser.mjs，然后仅用 createStore、store.subscribe、store.dispatch 三个 API 实现了一个计数器：

<script type="module">
  import * as Redux from 'https://unpkg.com/redux@latest/dist/redux.browser.mjs'

  function counter(state, action) {
    if (typeof state === 'undefined') return 0
    switch (action.type) {
      case 'INCREMENT': return state + 1
      case 'DECREMENT': return state - 1
      default: return state
    }
  }

  var store = Redux.createStore(counter)
  // store.subscribe(render) 与按钮 click -> store.dispatch(...)
</script>

需要注意的适用前提：这条路径仅适合演示或极轻量场景（如上文所示），因为 dispatch 只接受 plain object 形式的 action（见 src/createStore.ts 中 dispatch 对 isPlainObject 的校验），异步 action 需要中间件支持；而生态配套包普遍不提供 UMD 构建，真实项目仍应选择"包管理器 + 打包器"或上述官方模板路线。

小结：按场景选择安装方式

场景	推荐做法
新建 React/Next.js 应用	官方 Vite 模板或 Next.js with-redux 模板
在现有项目中引入 Redux	npm install @reduxjs/toolkit（React 项目再加 react-redux）
学习 Redux 底层原理	npm install redux，参考 examples/counter-vanilla/index.html
无打包器演示	浏览器 <script type="module"> 引入 redux.browser.mjs 构建
开发调试	安装 Redux DevTools Extension（配合 configureStore 自动接入）

以上所有命令与配置均以当前仓库的 docs/introduction/Installation.md、package.json 和 examples/ 目录的实际内容为依据，适用于 Redux 5.x 版本。