不仅仅是 Mock 服务：mock-h3，让前端也能优雅拥有后端能力

在前端开发中，Mock 服务几乎是不可或缺的：

需要快速搭建 Demo；
后端接口还没准备好；
或者需要模拟一些特殊场景的数据。

然而，现有的方案往往不够优雅，要么需要复杂配置，要么和实际部署环境脱节。

于是，我们基于 Vite + h3 ，实现了一款轻量、灵活的 Mock 插件 ------ mock-h3。

背景与需求

在设计之初，我们明确了几个核心目标：

Vite 插件化：即插即用；
完全自定义 ：支持 js/ts，接口灵活可控；
同端口运行：无跨域问题；
生产可用：打包后可直接用 Node 启动，无需额外 Nginx；
支持 TS/ESM：抛弃 CJS；
文件路由：一个文件即一个接口，结构清晰；
扩展能力 ：保留 h3 的 中间件/插件 生态；
数据库支持：可以在 Mock 服务中轻松接入数据库。

技术选型

在 Node 服务端框架中，我们重点考虑了 轻量、易用、类型友好 。

最终选择了 h3 v2：

内置 defineHandleEvent、readBody 等 API；
TypeScript 友好，类型提示完整；
比 express / koa 更轻量，配置更简洁。

基于此，我们开发了 mock-h3 插件 。

它是一个 与前端框架无关的服务端插件 ------ 无论你用 Vue、React 还是其他框架，都能直接集成。

常见 Mock 方案对比

特性 / 方案	mockjs	vite-plugin-mock	mock-h3（本项目）
实现方式	纯前端拦截，模拟数据	基于 express	基于 h3，轻量 Node 服务
类型支持	无类型提示	TS支持，但无类型提示	完全支持 TS/ESM，支持类型提示
文件路由	不支持，需要手动注册	支持（配置稍有复杂）	天然支持，一个文件一个接口配置简单
跨域问题	存在（需额外配置）	无跨域问题	无跨域，共享 Vite 端口
生产可用性	不可用	不推荐生产使用	满足小项目，生产可运行，打包部署
扩展能力	-	-	支持 h3 插件 & 中间件系统
数据库交互	-	-	支持，可直接接入数据库

可以看到，mock-h3 不仅覆盖了开发阶段的 Mock 需求，还能平滑过渡到生产环境，避免了「开发环境能跑，生产环境需要重写」的尴尬。

适用场景

mock-h3 并不是要替代所有 Mock 工具，而是针对以下场景特别合适：

快速原型 / Demo 搭建

不依赖后端接口，前端能独立完成演示，交付更快。
中小型项目 / 内部系统

前后端接口都由 Node 服务统一启动，不用单独配置网关或 nginx，部署简单。
长期需要 Mock 的项目

不仅能在开发阶段使用，还能在生产环境继续运行，避免重复造轮子。
需要简单数据库交互

可以直接在 Mock 服务中读写数据库，模拟更接近真实的业务逻辑。

如果你的需求只是前端临时造一些假数据（例如单纯的 UI 演示），可能用 mockjs 更简单；

但如果你希望 Mock 服务能 稳定、可维护，并最终走向生产环境 ，那么 mock-h3 会更合适。

快速上手

安装

bash 复制代码

pnpm add mock-h3 h3@beta -D

配置 vite.config.ts：

ts 复制代码

import { mockH3 } from 'mock-h3/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    mockH3()
  ]
})

默认目录结构

csharp 复制代码

servers/
├── middleware/              # 中间件
├── plugins/                 # 插件
└── routes/                  # 路由
    ├── user.get.ts          # GET 请求
    ├── edit.post.ts         # POST 请求
    └── ...

一个文件就是一个接口，结构直观，不会混乱。

高级能力

中间件

中间件按文件顺序依次加载，可通过命名控制顺序。

👉 参考：h3 中间件文档

插件

基于 h3 的插件机制，推荐使用 definePlugin 定义：

ts 复制代码

// logger.ts
import { definePlugin } from 'h3'

export default definePlugin((h3) => {
  if (h3.config.debug) {
    h3.use((req) => {
      console.log(`[${req.method}] ${req.url}`)
    })
  }
})

👉 参考：h3 插件文档

配置项

prefix ：接口前缀，默认 /api；
srcDir ：扫描目录，默认 servers；
build ：是否在生产环境启用，默认 true；
outputDir ：构建输出目录，默认 dist/servers。

部署方案

构建完成后，会在 dist/servers 下生成完整服务：

bash 复制代码

node dist/servers/app.mjs

此时，前端工程与 Mock 服务即可一同启动，静态站点与接口无需额外配置。

推荐方式：使用 Docker 部署，Node.js 版本 ≥ 22。

示例与开源地址

目前我们已在 Antdv Pro 中，将原有 nitro 服务替换为 mock-h3。

👉 项目地址：mock-h3

如果你喜欢这个项目，欢迎给 Antdv Pro 和 mock-h3 点个 ⭐️。

也非常欢迎提交 Issue 和 PR，让我们一起让这个插件更好用！ 🚀