1. 为什么要在 Nuxt 模板里引入 Mock 数据
做过前端的朋友大概都有过这种体验：页面骨架搭好了，样式调得差不多了，结果后端接口还没影，联调排期排在两周之后。这时候要么干等，要么自己手写一堆假数据塞进data里，改一次字段就得全局搜一遍替换。项目稍微大一点，这种硬编码的假数据就成了技术债，接口一上线，删都删不干净。
Mock.js 这个库就是冲着这个痛点来的。它的核心能力有两块：一是基于模板生成随机数据，比如'name|1-10': '★'这种语法能直接生成随机长度的字符串；二是拦截 Ajax 请求并返回模拟响应，让前端在完全没有后端的情况下也能跑通完整的请求链路。把它和 Nuxt 结合起来，价值就更明显了——Nuxt 本身有服务端渲染（SSR）和静态生成（SSG）两套渲染模式，模板层（也就是pages、components里的.vue文件）既可能在 Node 端执行，也可能在浏览器端执行，Mock 数据的注入时机和位置如果没搞对，轻则数据不显示，重则服务端渲染直接报错。
这篇内容适合三类人看：第一类是刚接触 Nuxt、想快速搭出可交互原型的开发者；第二类是正在做前后端分离项目、需要一套可维护假数据方案的中级前端；第三类是对 SSR 环境下全局对象注入机制不太熟悉、想借 Mock 这个场景把 Nuxt 生命周期理一遍的同学。我会从方案选型讲到具体落地，把服务端和客户端两种注入路径都拆开说清楚，最后附上我实际踩过的坑和排查思路。
需要提前说明的是，下面涉及的所有项目名、接口路径、字段结构都是虚构的示例，你在自己项目里替换成真实业务即可。核心思路和配置方法是通用的。
2. 方案选型：Mock 数据到底该在哪一层注入
2.1 三种常见注入位置的对比
在 Nuxt 里用 Mock.js，很多人第一反应是直接在.vue文件的data()里import Mock from 'mockjs'然后生成数据。这个做法能跑，但问题不少。我把它和另外两种方案放在一起对比一下，你就能看出差别。
| 注入位置 | 执行环境 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|
| 组件内直接引入 | 客户端为主 | 改起来快，不用配置 | 每个组件重复引入，SSR 下容易报window is not defined | 临时调试、单页面 Demo |
| 插件 + 全局注入 | 可控制端 | 一次配置全局可用，能区分服务端/客户端 | 需要理解 Nuxt 插件机制 | 中大型项目、需要 SSR |
| 独立 Mock 服务 | 独立进程 | 最接近真实后端，可跨项目复用 | 需要额外起服务，配置成本高 | 多端共用、团队协作 |
对于大多数 Nuxt 项目，我推荐插件 + 全局注入这条路。原因很直接：Nuxt 的插件系统天然支持通过文件名后缀区分运行环境，比如mock.server.js只在服务端跑，mock.client.js只在客户端跑，mock.js两端都跑。这个机制刚好能解决 Mock.js 在 SSR 下的兼容问题。
2.2 为什么 SSR 环境下不能随便引入 Mock
这里要展开讲一下原理，不然你遇到报错会一头雾水。Nuxt 的服务端渲染是在 Node.js 环境里执行的，Node 环境里没有window、document这些浏览器全局对象。Mock.js 内部有一部分逻辑依赖浏览器的XMLHttpRequest来做请求拦截，如果你在服务端渲染阶段引入了完整的 Mock.js，它去访问window就会抛错，页面直接白屏。
所以正确的做法是：服务端只用来生成静态的随机数据，客户端才用来拦截请求。生成数据这部分 Mock.js 是纯函数式的，不依赖浏览器环境，可以放心在服务端跑；而请求拦截那部分必须放到客户端插件里，并且要确保它在客户端 hydration 之后才执行。
提示：判断当前代码跑在哪个端，可以用
process.server和process.client这两个 Nuxt 注入的布尔变量，比自己去判断typeof window更语义化。
2.3 版本选择的一个小坑
Mock.js 这个库更新频率不高，社区里流通的版本比较杂。我实测下来，mockjs的 1.1.0 版本在 Nuxt 3 环境下配合 Vite 打包时，偶尔会出现default export解析异常。如果你用的是 Nuxt 3，建议在nuxt.config里把 mockjs 加到build.transpile数组里，让它走一遍转译，能规避大部分模块解析问题。Nuxt 2 的话基本开箱即用，不用额外配置。
3. 环境搭建与依赖配置的完整步骤
3.1 初始化项目与安装依赖
假设你已经有一个能跑的 Nuxt 项目，如果没有，用官方脚手架起一个最简结构就行。依赖安装这一步没什么花活，但要注意包管理器的选择——如果你团队用 pnpm，Mock.js 这种老库可能会有幽灵依赖问题，建议在.npmrc里加上shamefully-hoist=true，或者干脆用 npm/yarn 装。
# 安装 mockjs npm install mockjs --save-dev # 如果用的是 Nuxt 3，额外确认下版本 npm list mockjs装完之后，在项目根目录建一个mock文件夹，专门放数据模板和接口定义。这个目录结构建议提前规划好，不然后面接口一多就乱。
mock/ index.js # 统一出口 modules/ user.js # 用户相关接口 article.js # 文章相关接口 utils/ response.js # 统一响应格式包装3.2 配置 Nuxt 插件
在plugins目录下新建mock.js。这里有个关键点：如果你希望 Mock 数据在服务端渲染时就能用上（比如首屏就要展示随机生成的列表），那这个插件不能只在客户端跑，得让它在服务端也执行数据生成逻辑，但请求拦截部分要隔离出去。
// plugins/mock.js import Mock from 'mockjs' export default defineNuxtPlugin((nuxtApp) => { // 服务端和客户端都执行数据模板注册 // 但请求拦截只在客户端做 if (process.client) { // 动态引入拦截逻辑，避免服务端加载 import('~/mock/interceptor').then(({ setupInterceptor }) => { setupInterceptor(Mock) }) } // 把 Mock 实例挂到全局，模板里可以直接用 return { provide: { mock: Mock } } })然后在nuxt.config里注册这个插件：
// nuxt.config.js (Nuxt 2) export default { plugins: [ '~/plugins/mock.js' ], build: { transpile: ['mockjs'] } }// nuxt.config.ts (Nuxt 3) export default defineNuxtConfig({ plugins: [ '~/plugins/mock.js' ], build: { transpile: ['mockjs'] } })3.3 验证插件是否生效
配置完之后别急着写业务，先做个最小验证。在任意页面的模板里打印一下注入的 mock 对象：
<template> <div> <p>{{ testData }}</p> </div> </template> <script> export default { data() { return { testData: '' } }, mounted() { // 通过 inject 拿到插件 provide 的 mock const mock = this.$mock || this.$root.$mock this.testData = mock.Random.ctitle(5, 10) } } </script>如果页面上能显示出一段随机中文标题，说明插件注入成功。如果报$mock is undefined，检查一下插件的provide写法和你取值的方式是否匹配——Nuxt 2 和 Nuxt 3 在插件返回值处理上有差异，Nuxt 3 用nuxtApp.provide或者直接返回对象，取值时用useNuxtApp().$mock。
注意：Nuxt 3 的 Composition API 写法下，
this.$mock是不存在的，必须用const { $mock } = useNuxtApp()。这一点从 Options API 迁移过来的同学特别容易踩。
4. 数据模板设计与随机生成的核心技巧
4.1 Mock.js 模板语法速览
Mock.js 的数据模板语法是它的灵魂，掌握几个核心规则就能覆盖 90% 的场景。它的基本形式是'属性名|规则': 值，规则决定了值如何被随机化。
| 规则写法 | 含义 | 示例 | 生成结果示例 |
|---|---|---|---|
'name|1-10' | 字符串随机长度 | 'name|1-10': '★' | '★★★' |
'age|18-60' | 数字区间 | 'age|18-60': 0 | 35 |
'list|3' | 数组固定长度 | 'list|3': [{}] | 长度 3 的数组 |
'list|1-5' | 数组随机长度 | 'list|1-5': [{}] | 长度 1 到 5 |
'status|1' | 布尔值 | 'status|1': true | true或false |
'type|+1' | 递增数字 | 'type|+1': 1 | 1, 2, 3... |
这里有个容易搞混的点：'list|3': [{}]里的[{}]是模板，Mock 会把这个对象模板复制 3 份，每份里的字段再各自随机。如果你写'list|3': [{ id: 1 }]，那生成的三份数据 id 都是 1，因为固定值不会被随机化。想要每份 id 不同，得写成'list|3': [{ 'id|+1': 1 }]。
4.2 构建一个贴近真实业务的接口模板
光会用语法还不够，实际项目里接口返回的数据结构往往有嵌套和关联。我拿一个虚构的"文章列表"接口举例，展示怎么把模板设计得既真实又好维护。
// mock/modules/article.js import Mock from 'mockjs' const Random = Mock.Random // 生成单个作者信息 function genAuthor() { return { id: Random.guid(), name: Random.cname(), avatar: Random.image('100x100', Random.color(), '#fff', 'avatar'), bio: Random.ctitle(10, 30) } } // 生成单篇文章 function genArticle(index) { return { 'id|+1': index, title: Random.ctitle(8, 20), summary: Random.cparagraph(1, 3), cover: Random.image('750x400', Random.color(), '#fff', 'cover'), author: genAuthor(), 'tags|1-4': [Random.ctitle(2, 4)], 'viewCount|100-99999': 0, 'likeCount|0-5000': 0, publishTime: Random.datetime('yyyy-MM-dd HH:mm:ss'), 'status|1': ['published', 'draft', 'reviewing'] } } // 导出列表接口模板 export function getArticleList(count = 10) { return Mock.mock({ code: 200, message: 'success', [`data|${count}`]: [genArticle(1)] }) }这段代码里有几个设计考量值得说一下。第一，我把作者生成抽成了独立函数，因为实际业务里作者信息可能在多个接口复用，抽出来方便统一维护。第二，'id|+1': index配合传入的起始索引，保证每次调用生成的 id 是连续且不重复的，比纯随机 id 更接近真实数据库自增主键的行为。第三，status用数组随机取值，模拟了真实业务里的状态枚举。
4.3 让随机数据"看起来像真的"
Mock.js 内置的Random方法很丰富，但默认生成的数据有时候太"随机"了，反而不像真实业务数据。比如Random.ctitle()生成的中文标题是随机汉字拼凑的，读起来毫无意义。如果你要做演示给非技术人员看，这种数据会显得很假。
我的做法是准备一批语料池，用Random.pick()从池子里随机取，而不是纯随机生成。比如：
const titlePool = [ '前端工程化的三个关键节点', '从零搭建组件库的实践记录', '性能优化踩坑实录', '状态管理方案选型对比', '构建工具迁移经验分享' ] const title = Random.pick(titlePool)这样生成的数据虽然还是假的，但至少读起来像那么回事。语料池不用很大，二三十条就能覆盖大部分演示场景，而且维护成本极低。
实操心得：语料池建议单独放一个
mock/data/dict.js文件，按业务模块分组导出。这样接口模板和语料数据分离，改文案不用动逻辑代码。
5. 在 Nuxt 模板中消费 Mock 数据的两种路径
5.1 路径一：服务端直接生成，随首屏一起渲染
这是最省事的路径，适合那些不需要模拟请求、只是想在页面上展示随机数据的场景。因为数据在服务端就生成好了，首屏 HTML 里直接带着内容，SEO 友好，也不会有客户端闪烁。
在 Nuxt 2 的asyncData里可以这样写：
<template> <div> <article v-for="item in articles" :key="item.id"> <h3>{{ item.title }}</h3> <p>{{ item.summary }}</p> </article> </div> </template> <script> import { getArticleList } from '~/mock/modules/article' export default { async asyncData() { // 服务端执行，直接拿到数据 const res = getArticleList(8) return { articles: res.data } } } </script>Nuxt 3 的话用useAsyncData：
<script setup> import { getArticleList } from '~/mock/modules/article' const { data: articles } = await useAsyncData('articles', () => { return getArticleList(8).data }) </script>这条路径的关键在于：getArticleList是纯函数，不依赖任何浏览器 API，所以能在服务端安全执行。你只要保证模板里用到的 Mock 方法都是Random下的纯函数，就不会出问题。
5.2 路径二：客户端拦截请求，模拟完整链路
如果你想让前端代码和真实对接后端时保持一致——也就是照常发axios或fetch请求，只是请求被 Mock 拦截并返回假数据——那就得走客户端拦截这条路。这样做的好处是，接口一上线，你只需要把 Mock 拦截关掉，业务代码一行都不用改。
先写拦截逻辑：
// mock/interceptor.js import { getArticleList } from './modules/article' export function setupInterceptor(Mock) { // 拦截文章列表请求 Mock.mock(/\/api\/article\/list/, 'get', (options) => { // 从 URL 里解析分页参数 const url = new URL(options.url, 'http://localhost') const page = parseInt(url.searchParams.get('page') || '1') const pageSize = parseInt(url.searchParams.get('pageSize') || '10') const res = getArticleList(pageSize) return { code: 200, message: 'success', data: { list: res.data, page, pageSize, total: 100 } } }) // 拦截文章详情请求 Mock.mock(/\/api\/article\/detail/, 'get', () => { return Mock.mock({ code: 200, message: 'success', data: { id: '@guid', title: '@ctitle(8, 20)', content: '@cparagraph(5, 10)', publishTime: '@datetime' } }) }) }然后在页面里正常发请求：
<script> export default { data() { return { list: [], loading: false } }, async mounted() { this.loading = true try { const res = await this.$axios.get('/api/article/list', { params: { page: 1, pageSize: 10 } }) this.list = res.data.data.list } finally { this.loading = false } } } </script>这里有个细节要注意：Mock.js 的请求拦截是基于XMLHttpRequest的，如果你项目里用的是fetch或者axios的 fetch adapter，拦截会失效。axios 默认用 XHR，所以没问题；但如果你手动配置了adapter: 'fetch'，就得换回 XHR adapter，或者改用别的拦截方案。
5.3 两种路径怎么选
简单判断标准：看你的业务代码里有没有真实的请求调用。如果页面数据是直接通过函数调用拿到的，走路径一；如果页面是通过 HTTP 请求拿数据的，走路径二。实际项目里往往是混合的——首屏关键数据走路径一保证渲染速度，交互触发的数据走路径二模拟请求延迟和分页。
提示：路径二拦截的 URL 正则要写准确，
/\/api\/article\/list/这种写法能匹配到带查询参数的完整 URL，但如果你有/api/article/list/detail这种前缀相同的接口，正则会误伤。建议用更精确的匹配，或者在拦截函数里再做一次路径判断。
6. 常见问题与排查技巧实录
6.1 服务端渲染报 window is not defined
这是最高频的问题，几乎每个在 Nuxt 里用 Mock.js 的人都会遇到一次。报错堆栈通常指向mockjs内部的某一行，提示window未定义。
根因：Mock.js 在模块加载阶段就执行了一些依赖浏览器环境的代码，而 Nuxt 的服务端渲染会在 Node 里加载这个模块。
解决：把 Mock.js 的引入改成动态引入，并且只在客户端执行。前面插件那节已经给了写法，核心就是if (process.client) { import('mockjs') }。如果你确实需要在服务端用Random生成数据，可以单独引入mockjs/src/mock/random这个子模块，它不包含请求拦截逻辑，是纯函数集合。
6.2 拦截不生效，请求还是打到了真实接口
排查这个问题的顺序是这样的：
- 确认
setupInterceptor确实被调用了。在函数第一行加console.log，看客户端控制台有没有输出。 - 确认请求的 URL 和拦截正则匹配。把
options.url打印出来，和你的正则对一下。 - 确认请求方法匹配。
Mock.mock(url, 'get', fn)的第二个参数是方法，大小写敏感，写'GET'是不行的。 - 确认没有其他拦截器抢先。如果你项目里用了 axios 的请求拦截器，且拦截器里做了 URL 重写，Mock 拿到的可能是重写后的 URL。
我遇到过一次特别隐蔽的情况：项目里配了 axios 的baseURL，实际请求 URL 是https://api.example.com/api/article/list，而我的拦截正则只写了/api/article/list，理论上能匹配，但因为 Mock.js 对完整 URL 的匹配是从头开始的，导致没拦住。后来把正则改成/article\/list/这种更宽松的写法才生效。
6.3 生成的数据每次刷新都一样
如果你发现页面刷新后数据没变，大概率是因为数据在服务端生成后被缓存了。Nuxt 的useAsyncData默认会缓存结果，key 相同就不会重新执行。解决办法是给 key 加上时间戳或者随机数：
const { data } = await useAsyncData(`articles-${Date.now()}`, () => { return getArticleList(8).data })但这样会失去缓存带来的性能优势，所以更合理的做法是只在开发环境这么做，生产环境用固定 key。
6.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方向 | 解决方案 |
|---|---|---|---|
| 页面白屏，控制台报 window 未定义 | 服务端加载了完整 Mock.js | 检查插件是否区分了端 | 用 process.client 隔离拦截逻辑 |
| 请求未被拦截 | URL 或方法不匹配 | 打印 options.url 对比正则 | 调整正则，确认方法小写 |
| 数据不刷新 | useAsyncData 缓存 | 检查 key 是否固定 | 开发环境用动态 key |
| 打包后 Mock 失效 | 被 tree-shaking 移除 | 检查构建配置 | 加到 transpile 或 externals |
| 中文乱码 | 编码问题 | 检查响应头 | 一般不影响，Mock 返回的是 JS 对象 |
6.5 几个我踩过的坑
第一个坑是关于Mock.mock()的返回值。它返回的是一个新对象，而不是修改传入的模板。我一开始写成了const data = template; Mock.mock(data)，以为 data 会被填充，结果拿到的还是空模板。正确写法是const data = Mock.mock(template)。
第二个坑是正则里的斜杠转义。在 JavaScript 正则字面量里，/需要写成\/，但很多人从 URL 直接复制过来会忘记转义，导致正则语法错误。建议用new RegExp()构造，可读性更好。
第三个坑是生产环境打包。Mock.js 体积不小，如果你只在开发环境用，记得在构建配置里做条件引入，别让它进生产包。Nuxt 2 可以用process.env.NODE_ENV判断，Nuxt 3 可以用import.meta.dev。
// 只在开发环境注册 Mock 插件 const plugins = [] if (process.env.NODE_ENV === 'development') { plugins.push('~/plugins/mock.js') }7. 从 Mock 到真实接口的平滑切换策略
Mock 数据用起来爽，但迟早要切到真实接口。如果前期设计得好，切换应该是一行配置的事；如果设计得不好，那就是一场灾难。我总结了一套切换策略，核心思想是把"数据来源"抽象成一个可切换的开关。
具体做法是在项目里维护一个环境变量，比如USE_MOCK，然后在请求层做判断：
// utils/request.js const useMock = process.env.USE_MOCK === 'true' export async function request(config) { if (useMock) { // 走 Mock 拦截，实际还是发请求，只是被拦了 return axios(config) } // 走真实接口 return axios({ ...config, baseURL: process.env.API_BASE_URL }) }配合.env文件管理不同环境的配置：
# .env.development USE_MOCK=true API_BASE_URL= # .env.staging USE_MOCK=false API_BASE_URL=https://staging-api.example.com # .env.production USE_MOCK=false API_BASE_URL=https://api.example.com这样切换环境时，Mock 的开关自动跟着变，不需要手动改代码。而且因为业务代码里调用的始终是request函数，Mock 和真实接口对上层是透明的。
还有一个进阶玩法：部分接口用 Mock，部分用真实接口。比如用户登录必须走真实接口（因为要拿真实 token），但文章列表可以用 Mock。这时候可以在拦截配置里做白名单：
const mockWhitelist = [ /\/api\/article\/list/, /\/api\/article\/detail/, /\/api\/comment\/list/ ] // 只有白名单里的接口才拦截 mockWhitelist.forEach(pattern => { Mock.mock(pattern, 'get', handler) })这套策略我在几个项目里用过，从开发到联调的过渡非常顺滑，基本没有出现"切接口切出 bug"的情况。关键就在于前期别把 Mock 逻辑散落在各个组件里，统一收口到请求层和插件层，后面维护起来才轻松。
最后分享一个我个人的习惯：每次新增一个 Mock 接口，我都会在mock/modules对应的文件里写一行注释，标注这个接口对应的真实后端路径和负责人。这样联调的时候，我能快速定位到哪些 Mock 需要替换，不用一个个去翻代码。这个习惯看起来不起眼，但在接口数量上到几十个之后，能省下大量沟通成本。
