场景模拟

功能概述

场景模拟允许你为同一 API 端点定义多组 mock 响应，并通过场景配置在不同响应间切换。当你需要在不同开发上下文中使用不同的 mock 行为时（如测试、调试或演示环境），这个功能就很有用。

核心价值

• 上下文切换: 无需修改 mock 文件即可在不同 mock 数据集之间切换
• 按请求覆盖: 使用 X-Mock-Scene 请求头按请求动态切换场景
• 非侵入性: 未配置 scene 的 mock 保持通用，始终生效
• 优先级感知: 带场景的 mock 比通用 mock 具有更高的匹配优先级

插件配置

首先，通过插件配置中的 activeScene 选项定义激活的场景：

vite.config.ts

import { defineConfig } from 'vite'
import { mockDevServerPlugin } from 'vite-plugin-mock-dev-server'

export default defineConfig({
  plugins: [
    mockDevServerPlugin({
      activeScene: 'dev', // 仅激活 scene 为 'dev' 的 mock
    }),
  ],
})

你也可以配置多个激活场景：

mockDevServerPlugin({
  activeScene: ['dev', 'test'],
})

Mock 配置

为 mock 配置添加 scene 标识。未配置 scene 的 mock 为通用 mock，始终生效。

api.mock.ts

import { defineMock } from 'vite-plugin-mock-dev-server'

export default defineMock([
  // 通用 mock — 始终生效
  {
    url: '/api/user',
    body: { name: '默认用户' },
  },
  // 仅在场景 'admin' 匹配时生效
  {
    url: '/api/user',
    scene: 'admin',
    body: { name: '管理员', role: 'admin' },
  },
  // 仅在场景 'demo' 匹配时生效
  {
    url: '/api/user',
    scene: 'demo',
    body: { name: '演示用户', role: 'guest' },
  },
])

按请求覆盖场景

可以通过 X-Mock-Scene HTTP 请求头按请求覆盖场景。这会优先于插件的 activeScene 配置。

// 为此请求激活 'admin' 场景
fetch('/api/user', {
  headers: { 'X-Mock-Scene': 'admin' }
})

// 激活多个场景
fetch('/api/user', {
  headers: { 'X-Mock-Scene': 'admin,demo' }
})

匹配规则

1. 未配置 scene 的 mock 为通用 mock，不受场景限制，始终参与匹配。
2. 配置了 scene 的 mock，只有当其 scene 中任意一项与激活场景中任意一项匹配时才参与匹配。
3. 如果未配置 activeScene 且没有 X-Mock-Scene 请求头，带 scene 的 mock 不会匹配。
4. X-Mock-Scene 请求头覆盖插件的 activeScene 配置，仅对该请求生效。
5. 带 scene 的 mock 比通用 mock 具有更高的匹配优先级。

使用场景

场景1：多环境开发

在空数据、分页数据、错误状态等不同后端状态间切换，无需修改 mock 文件。

场景2：演示模式

创建专用的演示场景，返回精心设计的数据，通过配置 activeScene: 'demo' 快速切换。

场景3：自动化测试

在测试请求中使用 X-Mock-Scene 请求头验证不同的 API 响应场景，无需修改全局配置。