# @akfm/vite-plugin-storybook-mock-server-functions 中文文档

规范地址：https://npmcn.com/package/%40akfm/vite-plugin-storybook-mock-server-functions/

版本：0\.0\.0
npm 元数据更新时间：2026-07-24T15:03:55.019Z
中文译文更新时间：2026-11-05T22:28:37.383Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40akfm/vite-plugin-storybook-mock-server-functions
原文对照：https://npmcn.com/package/%40akfm/vite-plugin-storybook-mock-server-functions/?lang=original
项目主页：https://github.com/AkifumiSato/vite-plugin-storybook-mock-server-functions#readme
源码仓库：https://github.com/AkifumiSato/vite-plugin-storybook-mock-server-functions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：20.2 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：storybook ^9\.0\.0 \|\| ^10\.0\.0，vite ^5\.0\.0 \|\| ^6\.0\.0 \|\| ^7\.0\.0 \|\| ^8\.0\.0
- 首次发布：2026-07-24T14:49:58.198Z
- 最新版本发布：2026-07-24T15:03:54.168Z
- 近 30 天下载量：12146（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

将 Next.js 服务器动作( “ 使用服务器”) 替换为 Storybook fn () 模拟的 Vite 插件 .

## 安装

```sh
npm install @akfm/vite-plugin-storybook-mock-server-functions
```

也可以使用：`pnpm add @akfm/vite-plugin-storybook-mock-server-functions`、`yarn add @akfm/vite-plugin-storybook-mock-server-functions`、`bun add @akfm/vite-plugin-storybook-mock-server-functions`

## README

# @akfm/vite-plugin-storybook-mock-server-函数

[![npm version](https://img.shields.io/npm/v/@akfm/vite-plugin-storybook-mock-server-functions.svg)](https://www.npmjs.com/package/@akfm/vite-plugin-storybook-mock-server-functions) [![license](https://img.shields.io/npm/l/@akfm/vite-plugin-storybook-mock-server-functions.svg)](https://npmcn.com/package/%40akfm/vite-plugin-storybook-mock-server-functions/#readme-license)

页:1 [日本語](https://npmcn.com/package/%40akfm/vite-plugin-storybook-mock-server-functions/README_ja.md)

允许 Next.js App 路由器服务器动作的 Vite 插件(`"use server"`)在"故事书"内部独立运行.

Next.js Server Actions依赖于Next.js自己的捆绑器变换和服务器执行时的运行时间,所以把它们装入Storybook(即以Vite-based)导致构建或运行时间出错. 此插件检测带有以下功能: `"use server"` 指令并将其替换为 [`storybook/test`](https://storybook.js.org/docs/writing-tests/interaction-testing)是因为 `fn()`\-基于模拟函数,因此使用Server Actions的组件可以在没有真实服务器的情况下在故事书中渲染并测试.

## 特征

-   检测模块级别和函数级别 `"use server"` 指令 – 不需要调整现有的动作文件.
-   只将含有指令的函数替换为 `fn()` 模拟;文件中的其他一切(包括非动作导出)都未被触及.
-   让每个故事通过 `parameters.serverFunctions`,在故事之间自动重置模拟器.
-   船舶作为单一的Vite插件+一个装饰器——没有额外的"故事本"附加件可以安装.

## 支持的模式

-   **模块级指令**数字 : `"use server"` 在文件的顶端。 文件的每个导出函数都作为服务器动作处理.
-   **函数级(内含)指令**数字 : `"use server"` 在单个函数机构的顶端,不需要模块级指令。 这项工作涉及独立的函数声明/表达方式,以及物体或类的字段/方法的属性/表达方式,因此,在其他说明出口之间具有单一的指令性功能(例如: `api.create` 是服务器动作,而 `api.formatLabel` 以两种方式正确检测.

```ts
// actions/todo.ts (module-level — every export in the file is a Server Action)
"use server";
export async function createTodo(formData: FormData) {
  /* real server-side work */
}

// actions/delete-todo.ts (function-level, no module-level directive — only this
// function is a Server Action)
export async function deleteTodo(id: string) {
  "use server";
  /* real server-side work */
}

// actions/api.ts (function-level, only part of the object is a Server Action)
export const api = {
  create: async (formData: FormData) => {
    "use server";
    /* real server-side work */
  },
  formatLabel: (todo: Todo) => todo.title.toUpperCase(), // regular function, left untouched
};
```

无论哪种方式,在故事书构建时间,这些功能被模拟函数取而代之,通过 `storybook/test`是因为 `fn()`。 。 。 .

## 安装

```sh
npm install -D @akfm/vite-plugin-storybook-mock-server-functions
```

```sh
pnpm add -D @akfm/vite-plugin-storybook-mock-server-functions
```

```sh
yarn add -D @akfm/vite-plugin-storybook-mock-server-functions
```

要求数 `vite` 财务报告和审定财务报表 `storybook` 作为同伴的依赖关系.

## 设置

### 1\. 注册插件

将插件添加到 `.storybook/main.ts`是因为 `viteFinal`。 。 。 .

```ts
import { storybookMockServerFunctions } from "@akfm/vite-plugin-storybook-mock-server-functions";

const config = {
  framework: "@storybook/nextjs-vite",
  // ...
  viteFinal: async (viteConfig) => {
    viteConfig.plugins ??= [];
    viteConfig.plugins.push(storybookMockServerFunctions());
    return viteConfig;
  },
};

export default config;
```

### 2\. 登记装饰者

将装饰器添加到 `.storybook/preview.ts`在每个故事开始前 都重播所有游戏.

```ts
import { withServerFunctionMocks } from "@akfm/vite-plugin-storybook-mock-server-functions/runtime";

const preview = {
  decorators: [withServerFunctionMocks],
};

export default preview;
```

## 从故事中注入模拟执行

传出 a `Map<mock function, implementation function>` 通过 `parameters.serverFunctions` 在每层的基础上注入任何返回值或行为。 由于Vite的模块图是单通的,故事导入的函数就是所生成的插件的精确的模拟函数,因此可以直接用作Map键.

```tsx
import { createTodo } from "../actions/todo";
import { api } from "../actions/api";

export const Success: Story = {
  parameters: {
    serverFunctions: new Map([
      [createTodo, async () => ({ ok: true, id: "1" })],
      [api.create, async () => ({ ok: true })],
    ]),
  },
};
```

若为 `parameters.serverFunctions` 未设定,每个模拟默认为 `async () => undefined`。 。 。 .

非服务人员行动职能,如 `api.formatLabel` 未被转换,可随原实施而导入和使用.

## 选项

```ts
storybookMockServerFunctions({
  include?: FilterPattern; // default: [/\.[jt]sx?$/]
  exclude?: FilterPattern; // default: [/node_modules/]
})
```

`include` 编号 : `exclude` 直接传递到 [`@rollup/pluginutils`](https://github.com/rollup/plugins/tree/master/packages/pluginutils#createfilter)是因为 `createFilter`。 。 。 .

## 示例

`example/` 包含一个校验的故事簿应用程序 `@storybook/nextjs-vite`。 。 。 .

```sh
pnpm install
pnpm build
pnpm --filter example storybook
```

## 已知的限制

-   表格的再出口 `export { x } from './y'` 不支持.
-   职能级别的指令只在以下职能方面得到承认: `BlockStatement` 正体( 单表达式箭头函数如 `() => "use server"` 无法在体内持有指令,匹配Next.js自己的约束.
-   `parameters.serverFunctions` 设计绕过一个 `Map` 直接职能。 如果依赖于故事序列化(例如"故事本"所编的故事特征),请注意功能不能被序列化.
-   `oxc-parser` 依赖于平台特有的本地(napi)二进制。 这通常通过 npm/ pnpm 可选的OS/architecture 解决,但在不支持的运行时环境中可能无法工作.

## 许可证

麻省理工学院

## 常见问题

### @akfm/vite-plugin-storybook-mock-server-functions 是什么？

将 Next\.js 服务器动作\( “ 使用服务器”\) 替换为 Storybook fn \(\) 模拟的 Vite 插件 \.

### 如何安装 @akfm/vite-plugin-storybook-mock-server-functions？

在项目目录运行 npm install @akfm/vite-plugin-storybook-mock-server-functions，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：storybook（^9\.0\.0 \|\| ^10\.0\.0）、vite（^5\.0\.0 \|\| ^6\.0\.0 \|\| ^7\.0\.0 \|\| ^8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @akfm/vite-plugin-storybook-mock-server-functions 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @akfm/vite-plugin-storybook-mock-server-functions 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @akfm/vite-plugin-storybook-mock-server-functions 可以商用吗？

@akfm/vite-plugin-storybook-mock-server-functions 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @akfm/vite-plugin-storybook-mock-server-functions 的下载量有多少？

根据 npm 官方下载统计，@akfm/vite-plugin-storybook-mock-server-functions 在 2026/10/06 – 2026/11/04 这 30 天内被下载 12,146 次，日均约 405 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @akfm/vite-plugin-storybook-mock-server-functions 还在维护吗？

最新版本 0\.0\.0 发布于 2026/07/24（3 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/07/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。