configureServer 钩子用于配置开发服务器实例，需通过 server.app.use() 注册 Koa 中间件来拦截请求并实现 Mock；它不直接处理 HTTP 请求，仅提供配置时机。
在 Vite 中，server.configureServer 钩子不是用来直接拦截请求的中间件入口，它主要用于配置开发服务器实例（如 koa app），真正的请求拦截和 Mock 应该通过 configureServer 拿到 server 实例后，往其内部的 app（Koa 应用）中注册自定义中间件来实现。
理解 configureServer 的作用时机与能力
configureServer 是一个 Vite 插件钩子，在开发服务器启动前被调用，接收一个 server 对象。这个对象包含：
-
server.app：底层 Koa 实例，可直接 use 中间件 -
server.middlewares：已注册的中间件栈（只读，不建议直接 push） -
server.config：Vite 配置
⚠️ 注意：configureServer 本身不接收请求，也不返回响应，它只是“配置机会”。要拦截 HTTP 请求，必须往 server.app 上挂中间件。
在 configureServer 中注册路由级 Mock 中间件
推荐方式：使用 server.app.use() 添加 Koa 中间件，并用 ctx.path 或 ctx.url 匹配接口路径，手动设置响应。
- 匹配前缀如
/api/的请求，返回 JSON 数据 - 支持 GET/POST 等方法判断（
ctx.method） - 可解析请求体（需配合
koa-body或手动读取ctx.req）
示例（vite.config.ts）：
export default defineConfig({
plugins: [{
name: 'mock-server',
configureServer(server) {
server.app.use(async (ctx, next) => {
// 只处理 /api 开头且未被其他中间件响应过的请求
if (ctx.path.startsWith('/api/') && !ctx.body) {
const url = new URL(ctx.request.url, 'http://localhost');
const path = url.pathname;
if (path === '/api/user') {
ctx.status = 200;
ctx.set('Content-Type', 'application/json');
ctx.body = { code: 0, data: { id: 1, name: '张三' } };
return;
}
if (path === '/api/list' && ctx.method === 'POST') {
let body = '';
ctx.req.on('data', chunk => body += chunk);
await new Promise(resolve => ctx.req.on('end', resolve));
ctx.status = 200;
ctx.body = { code: 0, msg: '提交成功', data: JSON.parse(body) };
return;
}
}
await next(); // 继续后续中间件（如静态文件、SPA fallback）
});
}
}]
});
更工程化的 Mock 方案：结合 mockjs 或 msx
纯手写响应易维护性差。可引入 mockjs 生成随机数据，或用 msw（需搭配浏览器端拦截）；但若坚持服务端 Mock，推荐结构化管理：
- 新建
mock/目录，按模块拆分 JSON 或函数文件（如user.ts导出 handler） - 在中间件中动态 import 或 require 对应 mock 文件
- 利用路径映射自动加载，例如
/api/users → mock/users.ts
这样既保持逻辑分离，又便于后期替换为真实接口或切换环境。
注意事项与常见陷阱
实际使用时容易踩坑：
-
顺序很重要：你的中间件越早
use，越可能捕获请求；但不要放在static中间件之前，否则会拦截 HTML/JS/CSS 请求 -
避免重复响应：务必检查
!ctx.body或ctx.respond === false，防止多次设置 body 报错 -
跨域问题：本地开发默认同源，无需额外配置 CORS；如需测试跨域行为，可手动加
ctx.set('Access-Control-Allow-Origin', '*') -
HMR 不重启 server：修改
configureServer代码不会触发 server 重载，需手动重启 vite 进程
不复杂但容易忽略细节，关键是把 Mock 当作标准 Koa 中间件来写，而不是试图“劫持”某个钩子函数本身。
