Redux Toolkit自定义JSDoc调用时被覆盖的问题排查

RTK 内置的 ActionCreatorWithOptionalPayload 这类 action creator 类型自带通用 JSDoc 注释，其中的 @inheritdoc 会让 TypeScript 在解析 dispatch 调用时，优先使用 RTK 预设的类型注释，而非你在 createAction/createSlice 中定义的自定义注释。这是因为 dispatch 的默认类型（Dispatch<AnyAction>）会匹配 RTK 通用的 action creator 类型，导致你的自定义注释被覆盖。

1. 自定义 AppDispatch 类型，缩小类型范围 #

在 store 文件中定义精准的 AppDispatch 类型，让 TypeScript 明确知道 dispatch 只能接收你项目中定义的 action，从而优先识别自定义注释：

// store.ts
import { configureStore } from '@reduxjs/toolkit';
import userSlice from './features/userSlice';

const store = configureStore({
  reducer: {
    user: userSlice.reducer,
  },
});

// 导出精准的 AppDispatch 类型
export type AppDispatch = typeof store.dispatch;

export default store;

在组件中使用 AppDispatch 替代默认的 Dispatch：

import { useDispatch } from 'react-redux';
import type { AppDispatch } from '../store';
import { updateUser } from '../features/userSlice';

const dispatch = useDispatch<AppDispatch>();
// 此时调用 dispatch(updateUser(...)) 会显示你的自定义注释

2. 导出 action 时显式添加 JSDoc #

直接在导出 action 的语句上添加自定义注释，TypeScript 会优先读取导出层级的注释，覆盖 RTK 内部类型的注释：

// userSlice.ts
import { createSlice } from '@reduxjs/toolkit';

const userSlice = createSlice({
  name: 'user',
  initialState: { name: '', age: 0 },
  reducers: {
    updateUser: (state, action) => {
      state.name = action.payload.name;
      state.age = action.payload.age;
    },
  },
});

/**
 * 更新用户基本信息
 * @param payload - 包含用户姓名和年龄的对象
 * @returns 更新用户的 action
 */
export const { updateUser } = userSlice.actions;

用 createAction 时同理：

/**
 * 更新用户基本信息
 * @param payload - 包含用户姓名和年龄的对象
 * @returns 更新用户的 action
 */
export const updateUser = createAction<{ name: string; age: number }>('user/updateUser');

3. 显式断言 action creator 类型（小众场景） #

如果上述方法无效，可以通过类型断言强制 TypeScript 使用你的注释：

/**
 * 更新用户基本信息
 * @param payload - 包含用户姓名和年龄的对象
 */
export const updateUser = createAction<{ name: string; age: number }>('user/updateUser') as typeof updateUser;

这种方式会让 TypeScript 忽略 RTK 内部类型的注释，直接使用你定义的内容。

注意事项 #

不要直接修改 RTK 源码中的类型定义（比如去掉 @inheritdoc），因为更新 RTK 后修改会被覆盖，且会影响整个项目的类型提示一致性。

内容的提问来源于stack exchange，提问作者Seth Lutske