企业官网建设流程全解析

“用Nuxt重构已有Vue项目”这个活儿，我在实际项目里折腾过不止一次。表面上看是换框架，实际上牵一发动全身：请求层要重新落地、UI库的字体得换、编辑器这种重度依赖浏览器的组件会在SSR阶段直接把你打懵，再配上经典的localStorage is not defined，新手第一次跑起来会发现自己全是在跟脚手架默认行为作斗争。这篇文章我就按实际重构顺序，把Axios根域名、Vuetify字体、Mavon编辑器这三块硬骨头怎么啃，以及SSR环境下一串“浏览器对象未定义”的异常怎么排查，完整过一遍。

1. 重构前的准备：先想清楚Nuxt到底解决了你什么问题

1.1 为什么要把做得好好的Vue项目挪到Nuxt

很多团队把已有Vue项目重构成Nuxt，核心诉求就三个：SEO、首屏速度、工程化约束。SPA是空壳HTML加一堆<script>，搜索引擎爬虫能看到的内容极其有限；首屏要等JS下载、解析、执行完毕才渲染，弱网环境下白屏时间相当难堪。Nuxt带来服务端渲染（SSR），页面HTML直接由服务端生成，爬虫拿到的是完整内容，首屏也是直接可读的DOM，这两个痛点能同时缓解。

除此之外Nuxt还顺手带来了一些工程化上的约定：pages目录即路由、plugins目录统一注册插件、middleware干路由守卫、store内置Vuex。这些约定本身不带业务逻辑，但在团队协作时很有价值——每个人进来都按一个套路写代码，不用在路由表、初始化流程、全局状态上反复横跳。加上Nuxt本身有服务端能力和中间件机制，以后要加接口聚合、Cookie解析、服务端转发这类需求，不用再单独起一个BFF服务，直接在Nuxt里就能搞定。

不过别把它想成一键迁移。项目里凡是依赖window、document、localStorage、navigator的代码，在服务端渲染阶段全部会炸。重构前第一件事，就是给全项目做一次“浏览器对象依赖体检”，统计到底有多少地方在setup、created、mounted、模块顶层直接读取这些全局对象。这个统计结果直接决定重构工作量是大改还是小改。

1.2 把交互、渲染、业务三个层次拆开评估

我习惯在动手前把代码按三个层次过一遍：

• 纯业务逻辑层：API调用、数据转换、权限判断、工具函数。这层只要不直接读浏览器对象，基本可以原样搬进Nuxt，重点改请求路径和异常处理。
• 渲染层：模板、指令、组件生命周期。Vue组件本身在Nuxt里可以直接用，但要检查每个组件在mounted之前做了什么、有没有在初始化阶段访问DOM，以及第三方组件库是否兼容服务端渲染。
• 交互层：事件绑定、滚动监听、弹窗定位、剪贴板、文件上传。这层代码几乎都离不开浏览器环境，重构成Nuxt时要么在客户端生命周期里执行，要么用<client-only>包一层，要么动态导入时关掉SSR。

以我曾经重构过的项目为例（某内容管理后台），三个层次占比大概是45%、35%、20%。交互层占比不大但有极强的破坏性，任何一个弹窗组件在SSR阶段被实例化都可能直接抛错。先把这三个层次的边界划清楚，后面填坑就有路线图了。

重构过程中我还会顺手做一件事：把项目里所有全局工具函数过一遍，给“纯函数”和“浏览器相关函数”打上标记。这不是形式上的分类，而是为了让团队成员知道哪些函数可以在服务端安全调用，哪些必须在mounted里执行。有了这个标记，后面处理localStorage is not defined这类问题时，可以直接从异常堆栈定位到具体的函数文件，不用一行一行猜。

2. Axios默认根域名：把请求层的坑一次性填平

2.1 别在组件里写死baseURL

Vue项目里许多人习惯在每个页面的请求里直接写axios.get('http://api.example.com/user')，或者全局axios.defaults.baseURL = 'http://api.example.com'。前者在Nuxt里继续能跑，但会造成两个问题：一是环境切换时全局搜索替换URL，二是服务端渲染期间发出的请求同样走这个地址，DNS解析、跨域、内网路由全混在一起，排错体验极差。

Nuxt里正确的做法是把Axios配置收敛到插件和运行时配置里。我选的是@nuxtjs/axios模块加runtimeConfig的组合，处理nuxt.config.js时如果你用的是Nuxt 2，可以放publicRuntimeConfig和privateRuntimeConfig；Nuxt 3则直接走runtimeConfig.public。这样做的核心逻辑是：发布到不同环境时，配置文件里只换一个环境变量，所有请求自动指向正确的根域名，不用改一行业务代码。

2.2 环境变量与运行时配置的配合

以Nuxt 2 +@nuxtjs/axios为例，关键配置长这样：

// nuxt.config.js export default { publicRuntimeConfig: { axios: { baseURL: process.env.API_BASE_URL || 'http://127.0.0.1:3000/api' } }, modules: [ '@nuxtjs/axios' ], axios: { // 这里的配置是模块级别的，优先于默认值 } }

然后在插件里把根域名装进Axios实例：

// plugins/axios.js export default function ({ $axios, $config }, inject) { $axios.defaults.baseURL = $config.axios.baseURL $axios.onRequest(config => { // 统一的请求头注入，比如带token return config }) $axios.onError(error => { const code = error.response && error.response.status if (code === 401) { // 统一跳登录或刷新token } return Promise.reject(error) }) }

这里有个容易忽略的点：服务端渲染阶段发请求用的baseURL，和浏览器端用的baseURL，很可能是两个值。服务端在机房内网，可以直接走内网域名或容器名；浏览器端只能走公网域名。所以真正的生产项目我会把配置拆成两个：

publicRuntimeConfig: { axios: { browserBaseURL: process.env.BROWSER_API_BASE_URL, baseURL: process.env.API_BASE_URL } }

@nuxtjs/axios内部是支持browserBaseURL和baseURL分开设置的。这个设计的价值在于，服务端请求不经过公网，又不暴露内网结构，客户端请求则走CDN或网关，整体链路更稳。

2.3 关于本地开发代理和跨域的几个提醒

本地开发时，前端跑在localhost:3000，接口可能跑在localhost:8080，直接跨域会导致Cookie带不上、CORS预检失败等一系列问题。@nuxtjs/axios配合proxy模块可以解决：

modules: [ '@nuxtjs/axios', '@nuxtjs/proxy' ], axios: { proxy: true, baseURL: '/api' }, proxy: { '/api/': { target: 'http://localhost:8080', pathRewrite: { '^/api/': '' } } }

这段配置的妙处在于写了一行proxy: true之后，baseURL变成相对路径/api，所有请求先打到Nuxt自身的/api路由上，由Nuxt服务端转发到目标后端。这样本地没有了跨域，SSR阶段请求也是同源路径，不用区分内外网。上线时则把baseURL换成公网环境变量，整个迁移文件只动一处。

实操心得：如果你接手的是一个历史较长的Vue项目，先全局搜索axios.create({ baseURL: ... })、axios.defaults.baseURL、以及散落在各文件里的完整URL字符串。最好写一个临时的检查脚本，把所有直接写死域名的地方列出来。我碰到的项目里，有将近三成请求没有走统一实例，直接import axios from 'axios'然后axios.get，这种代码在Nuxt里不会错，但会让你失去统一拦截、错误处理、携带凭证的能力。重构请求层的价值就在这里，不止是换根域名，而是让所有请求经过同一个出口。

3. Vuetify字体切换：一个老生常谈却总有人卡住的配置

3.1 先分清你要换的是“Vuetify默认字体”还是“全局字体”

Vuetify 2.x默认字体栈是Roboto，Roboto这个字体如果在国内网络环境下没加载成功，页面看起来会有一瞬间的字体闪跳，甚至一直停留在系统默认字体上。Vuetify 3把字体相关的SCSS变量保留了下来，但换字体这件事的逻辑没变——Vuetify的字体是通过SCSS变量注入的，你要覆盖它，就得在样式层面按它的契约来。

很多人以为改字体只需要在nuxt.config.js里往vuetify配置项传一个customProperties或iconfont就够了，其实字体根本不是从这里换的。Vuetify的字体变量定义在styles/settings/_variables.scss里，其中$body-font-family、$heading-font-family、$font-size-root这几个变量决定了全局字体和字号。要换成自定义字体，最干净的方式是重写这几个SCSS变量。

3.2 Nuxt + Vuetify的字体配置完整示例

以Nuxt 2 + Vuetify 2为例，先在assets/scss/variables.scss里做变量覆盖：

// assets/scss/variables.scss $body-font-family: 'PingFang SC', 'Microsoft YaHei', 'Helvetica Neue', Arial, sans-serif; $heading-font-family: $body-font-family; $font-size-root: 16px;

然后在nuxt.config.js里把它接进Vuetify的样式管线：

// nuxt.config.js export default { css: [ '~/assets/scss/variables.scss' ], vuetify: { treeShake: true, defaultAssets: { font: true, // 这里控制是否加载Vuetify默认字体 icons: ['mdi'] } } }

如果你用的是@nuxtjs/vuetify模块，模块内部会自动把assets/scss/variables.scss作为Vuetify自定义变量文件加载，你甚至不需要手写一份新的scss去覆盖，直接在nuxt.config.js里指定：

vuetify: { customVariables: ['~/assets/scss/variables.scss'], treeShake: true, defaultAssets: { font: { family: 'Noto Sans SC' } } }

这里defaultAssets.font是Vuetify模块提供的快捷方式，它会在页面里自动加一段Google Fonts的链接。但国内生产环境访问Google Fonts是很不稳定的，我一般不会依赖这个快捷方式，而是关闭默认字体，把字体文件托管到自己的静态资源或CDN上。

3.3 字体文件的自托管方案和加载时序

关掉自动加载字体后，我在static/fonts/下放好字体文件，然后在nuxt.config.js里用head.script或直接在layouts/default.vue里手动引入@font-face。以layout里引入为例：

<!-- layouts/default.vue --> <style lang="scss"> @font-face { font-family: 'MyCustomFont'; src: url('~/static/fonts/MyCustomFont.woff2') format('woff2'), url('~/static/fonts/MyCustomFont.woff') format('woff'); font-display: swap; font-weight: 400; } </style>

注意url('~/static/fonts/...')在Vue SFC的style里不一定能不能正确解析，我实践下来更稳妥的做法是用~assets/fonts/，即把字体放进assets目录，通过Webpack的url-loader处理。路径问题的坑很容易踩，先把字体文件放在assets/fonts/下，然后这样引用：

@font-face { font-family: 'MyCustomFont'; src: url('~assets/fonts/MyCustomFont.woff2') format('woff2'); }

这里推荐font-display: swap，它保证字体文件还在加载时，页面先用回退字体渲染文本，不会出现不可见文字（FOIT）的尴尬体验。切换字体之后要实测一下不同操作系统的渲染差异，尤其Windows下中文字体的渲染高度、粗体表现和macOS完全不同，建议在变量里把回退字体链写全：'PingFang SC'、'Microsoft YaHei'、'Noto Sans SC'、sans-serif。

我踩过的坑：treeShake开启后，Vuetify会按需打包样式，如果只在部分组件里设置了自定义字体变量、另一部分组件没设置，可能出现同一个页面左边是自定义字体、右边还是Roboto的情况。排查方法是在浏览器里选中文本查看computed style的font-family，看是哪个选择器优先级更高。Vuetify的.v-application样式来自预编译的CSS文件，如果把自定义变量文件放错位置，它根本不会参与编译。所以务必确认customVariables指向的文件真的被模块加载了，最简单的验证方式是往variables.scss里写一个明显不合法又可见的变量（比如把$font-size-root: 999px），看页面字号有没有变化。

4. Mavon编辑器接入Nuxt：SSR环境下最典型的第三方组件适配

4.1 Mavon编辑器为什么在Nuxt里会炸

Mavon编辑器（mavon-editor）是一个基于Vue的Markdown编辑器组件，内部操作大量DOM：toolbar渲染、代码高亮、图片上传预览、滚动联动、粘贴剪切板读取。这些操作在浏览器里毫无压力，但在Nuxt的SSR阶段，组件在Node.js环境里执行render函数时会直接访问document对象——Node环境压根没有这个对象，于是抛出的就是经典的document is not defined、window is not defined。

理解了这一点，解决方案就变得清晰：让Mavon编辑器只在客户端渲染，服务端完全不碰它。Nuxt对这类场景提供了两个现成工具：<client-only>组件和ssr: false的动态导入。

4.2 用client-only包一层

最直观的方式是在模板里包上<client-only>：

<template> <div> <client-only> <mavon-editor v-model="content" :toolbars="toolbars" @img-add="handleImgAdd" /> </client-only> </div> </template> <script> import MavonEditor from 'mavon-editor' import 'mavon-editor/dist/css/index.css' export default { components: { MavonEditor }, data() { return { content: '', toolbars: { bold: true, italic: true, header: true, link: true, image: true } } } } </script>

需要注意一点：<client-only>内部的组件在服务端渲染阶段不会输出任何内容，也就是说当前页面对搜索引擎展示的内容里，Markdown正文区域是空的。如果这个页面需要被SEO收录，光包client-only不够，你应该在服务端渲染时额外输出编辑器的只读预览内容（把Markdown渲染成HTML），或者至少在<client-only>外面放一个<noscript>或静态占位。我的经验是，展示型内容（用户写的文档、文章）必须保留SSR版本，编辑功能才走客户端渲染。后来我把这个方案改成了双通道：正文区用markdown-it做服务端渲染输出，编辑器只在需要编辑时才切换出来，SEO和体验兼顾。

4.3 动态导入加ssr: false的进阶玩法

包client-only虽然省事，但组件的JS还是会打进服务端bundle，万一Mavon编辑器内部有副作用（比如在模块顶层执行了浏览器API），依然会在构建或启动阶段出问题。更彻底的方案是动态导入并显式关闭SSR：

export default { components: { MavonEditor: () => import('mavon-editor').then(m => m.default || m) } }

放在Nuxt里还要配合ssr: false：

const MavonEditor = () => import('mavon-editor').then(m => m.default || m)

更严谨的做法是新建一个包装组件，用nuxt.config.js里的build.extend把它从服务端排除：

build: { extend(config, { isServer }) { if (isServer) { config.externals = config.externals || [] config.externals.push('mavon-editor') } } }

把mavon-editor加入服务端externals，意味着服务端打包时不编译这个模块，运行时也不加载它。配合客户端动态导入，才能真正做到“服务端零接触”。这种写法对依赖了window、document的第三方库都适用，不止MavonEditor一个。

4.4 图片上传和自定义工具栏的配置细节

Mavon编辑器默认的图片上传是把图片转成base64存在正文里，这种方案在本地Demo没问题，但生产环境很快会把接口请求体和数据库字段撑爆。我一般通过@imgAdd事件接管上传逻辑，先把图片传到自己的对象存储，再回填URL：

async handleImgAdd(pos, $file) { const formData = new FormData() formData.append('file', $file) try { const { data } = await this.$axios.post('/upload/image', formData) this.$refs.md.$img2Url(pos, data.url) } catch (e) { this.$toast.error('上传失败') } }

这里有个Vue 2 + Nuxt 2的经验：$refs.md的md必须在模板里给Mavon编辑器组件加上ref="md"，且$img2Url是Mavon内部方法，操作的是当前编辑器的内容区DOM。如果你用client-only包裹且编辑器还没有完成挂载，this.$refs.md会是undefined，所以上传回调在@imgAdd里触发时通常没问题，因为图片事件必然发生在已有DOM之后。

工具栏配置也很容易忽略语言问题。MavonEditor的默认文案是中文，如果你需要英文或其他语言，得通过language属性设置，并且把对应语言包import进来。这个属性在设计上只在初始化时生效，运行时切换要通过一个key变化强制重建组件，跟Vuetify的locale用法差不多。这些细枝末节在官方文档里都有，但接入Nuxt后SSR的干扰常常让人误以为是配置没生效，其实只是组件没被客户端正确重建。

5. 高频异常实录：那些让人头疼的localStorage/window/document未定义问题

5.1 先弄明白异常的本质：Node环境没有浏览器全局对象

Nuxt服务端渲染是在Node.js进程中跑Vue组件的render函数，生成HTML字符串。Node进程里没有window、document、localStorage、navigator、sessionStorage、location这些浏览器全局对象。你的组件代码一旦在校验undefined之前直接访问它们，进程就会抛ReferenceError。这个错误有个特征：在本地开发时不一定复现，或者在首屏刷新时出现并伴随整个应用白屏。

真正让人困惑的不是错误本身，而是它的隐蔽性。很多第三方库和业务模块都有一层“间接依赖”——不是你的代码直接访问window，而是库内部某个模块在加载时访问了window。典型的例子：某个工具函数库在模块顶层使用了window.innerWidth做初始化判断，你在组件里只是简单import这个库，服务端加载模块时就已经炸了，跟你在哪里调用无关。这类模块顶层副作用是SSR迁移中最难排查的一类。

5.2 五个典型场景与对应修复方案

我把项目中遇到的高频报错场景整理成一个表，标出每种情况的判断要点和修法：

先看最普遍的组件初始化问题。修复不是简单地把代码搬到mounted就完事，还要考虑数据的一致性。我在项目里用到的模式是在mounted里读值并写入Vuex或组件data，服务端只负责渲染占位内容：

data() { return { token: '', theme: 'light' } }, mounted() { // 客户端环境才能安全访问 localStorage if (process.client) { this.token = localStorage.getItem('token') || '' this.theme = localStorage.getItem('theme') || 'light' } }

这样SSR阶段不会炸，客户端首次渲染时也能正确恢复状态。注意这里process.client是Nuxt提供的环境标记，编译时就会被替换成布尔值，理论上不会有运行时代价。

第二个场景是第三方库的模块顶层副作用，修法要暴力一些。以某个图表库为例，它在入口文件里就访问了document，我的做法是单独封装一个客户端组件：

<template> <div ref="chart"></div> </template> <script> export default { name: 'ClientChart', mounted() { // 动态导入第三方库，只在客户端执行 import('some-chart-lib').then(({ default: ChartLib }) => { this.chart = new ChartLib(this.$refs.chart) }) } } </script>

然后在使用处用<client-only>包裹或动态注册组件，彻底切断服务端的模块加载链路。这也是我在Mavon编辑器那一段提到的思路的通用版。

第三个场景是Nuxt插件。插件的默认加载时机是“所有页面”，包括服务端渲染阶段。如果插件里写了localStorage.getItem，整个应用启动就直接挂掉。修复方式两种：加process.client判断，或者在nuxt.config.js里把插件标记为客户端专用：

plugins: [ { src: '~/plugins/local-storage.js', mode: 'client' } ]

mode: 'client'的插件不会被加载到服务端bundle里，是最省心的处理。注意Nuxt 3里这个选项改成了{ client: true }的写法，迁移到Nuxt 3时要注意API变化。

第四个场景是Vuex store的state函数里直接初始化localStorage：

export const state = () => ({ token: localStorage.getItem('token') || '' })

这段代码在任何SSR环境下都是必炸的，因为state初始化在服务端渲染阶段就会执行。修复方式是抛弃在state里读浏览器对象，改为服务端给默认值，客户端在mounted之后派发一个initFromStorage的action：

export const state = () => ({ token: '' }) export const mutations = { SET_TOKEN(state, token) { state.token = token } } export const actions = { initFromStorage({ commit }) { if (process.client) { commit('SET_TOKEN', localStorage.getItem('token') || '') } } }

在应用入口处调用initFromStorage即可。注意这里“抛弃在state里读”这一步很重要，哪怕你都做了环境判断，只要有另一个模块在服务端引用了这个store，仍然有机会触发读取逻辑。

第五个场景是生命周期里的浏览器API，修复思路和第一个场景类似，把created里的逻辑挪到mounted。之所以单独拎出来说，是因为有些API只能在created里拿到路由快照（比如读取当前路由参数），挪到mounted后参数来源要换一种方式获取。我遇到的案例是某支付组件在created里用navigator.userAgent判断移动端还是PC端，这个判断在SSR阶段可以用req.headers['user-agent']代替，其实服务端拿到的User-Agent更准确，因为那是真实请求带过来的。这类“浏览器对象”在服务端是有替代方案的，值得按业务场景单独设计。

5.3 排查这类异常的通用方法论

面对xxx is not defined，我的排查顺序固定三件事：

1. 看堆栈第一行：判断异常是发生在渲染阶段还是事件回调阶段。渲染阶段的异常会导致整个请求500或白屏，事件回调阶段的异常通常只影响当前交互。区分这两者决定了你要不要先重启开发环境、清服务端缓存。

2. 看触发时机：是刷新页面（SSR渲染路径）就报，还是进入某个路由才报，还是点击某个按钮才报。刷新即报大概率是组件渲染阶段或模块加载阶段的问题；路由切换才报可能是某个懒加载组件在客户端实例化时的副作用；按钮点击才报则是纯客户端问题，跟SSR关系不大。

3. 用环境标记切割：在可疑代码处临时加上if (process.client) { console.log('reach client') }之类的探针，看服务端日志和浏览器控制台各自打印了什么。这种线上二分法比翻代码高效得多。

还有一个体力活技巧：在nuxt.config.js里暂时禁用SSR（ssr: false）跑一遍项目。如果所有异常消失，说明全部是SSR环境引起的；如果依然报错，说明项目本身就有浏览器对象依赖问题，跟重构Nuxt无关。这个简单的开关能帮你快速划分责任边界，我在重构中后期几乎天天用它。

5.4 一套可以抄作业的浏览器对象封装

与其每次在业务代码里写if (process.client)，不如封装一个storage工具，屏蔽环境差异：

// utils/storage.js const isClient = typeof window !== 'undefined' export const storage = { get(key) { if (!isClient) return null return localStorage.getItem(key) }, set(key, value) { if (isClient) { localStorage.setItem(key, value) } }, remove(key) { if (isClient) { localStorage.removeItem(key) } } }

业务代码里统一用storage.get('token')，服务端自动返回null，客户端正常读写。提交前全局搜索一下，把所有的localStorage.直接调用都替换成这个封装，能消灭掉七成以上的本地存储相关SSR异常。同理，window的访问可以封装成utils/window.js，用typeof window !== 'undefined'做保护。

这套封装解决了“会不会炸”的问题，但没有解决“数据一不一致”的问题——比如页面A在客户端已经写了localStorage，刷新时SSR输出的HTML里是按空值渲染的，客户端会再走一次读取并触发更新。这个过程中的闪烁，需要用v-if或一个initialized标志位来控制组件展示时机。我在有些列表页就是用v-if="initialized"来避免空值闪现的。

6. 重构收尾阶段的多环境验证清单

主体功能迁移完以后，我会按下面这份清单做一遍系统性验证，每一项都有明确目的，避免上线前才发现隐蔽问题：

• 本地开发模式：npm run dev跑起来，正常热更新、正常请求、正常SSR刷新。这个阶段重点看mounted前后的渲染差异和字体加载情况。
• SSR模式构建：npm run build && npm run start，模拟生产环境。重点验证window is not defined是不是彻底消失，以及构建产物里是否还有不该出现的浏览器对象访问。
• 多环境域名切换：分别以测试环境、生产环境的API_BASE_URL启动，确认Axios的baseURL在各环境都自动替换为正确的根域名。
• 刷新与直接访问：直接输入URL和刷新页面（走服务端渲染），看内容是否完整输出、编辑器是否正常显示、页面有没有因客户端重新渲染导致的闪烁或样式漂移。
• 低网速/弱网模拟：关掉部分JS资源，确认首屏HTML已经包含了关键内容，字体和各样式不会因为网络问题塌陷。
• 爬虫模拟：用禁用JS的工具或直接在服务器端curl页面，观察HTML里是否包含了正文内容，确认SEO改造是有效的。

每个环节我都会留一个检查日志，记录当时发现了什么、怎么修的。重构这种大动作，最容易出现“修好一个地方又坏掉另外一个地方”的连锁反应，留下日志能给回滚提供依据。我习惯在代码分支上按阶段提交：refactor/axios、refactor/vuetify-font、refactor/mavon-editor、refactor/ssr-fix，每个阶段都是独立可构建的提交点。这样如果某个环节出了问题，可以精确回退到上一个稳定点，而不是整个重构混成一锅粥再倒回去。

最后再分享一个经验：重构完成后的第一周，让团队里的每个人都至少经历一次“从克隆代码到把环境跑起来”的过程。这个过程暴露的文档缺失、环境变量遗漏、启动命令问题，往往比代码逻辑问题更影响效率。我在项目里就把环境变量整理成了一份.env.example，注明每个变量的含义和来源，这个文件成了新同事上手最快的入口。