把项目从 Nuxt 3 升到 Nuxt 4 的那一周我几乎把当年踩过的坑重新踩了一遍。最直观的感受是Nuxt 4 把代码块的组织方式彻底重新洗牌了——app/、server/、shared/ 各管一摊以前散在根目录的组件、组合式函数、工具函数全部要搬去新位置。很多人升级完只关注页面能不能正常渲染却忽略了代码块的物理位置、加载时机、缓存策略这些底层逻辑结果项目一变大构建变慢、首屏变重、离线不可用各种问题全冒出来。这篇文章就把我从迁移踩坑、逐步优化到落地完整方案的整个过程写出来核心围绕 Nuxt4 代码块怎么拆分复用、怎么控制加载体积、怎么配合 PWA 做离线缓存与接口缓存三个大方向。不管你是刚接触 Nuxt 4 的新手还是正在考虑从旧版本升级的老项目维护者这套优化技巧都值得直接抄作业。1. Nuxt 4 的代码块为什么值得重新设计1.1 从 Nuxt 3 到 Nuxt 4目录结构颠覆了什么Nuxt 4 发布后给我冲击最大的是目录结构。旧版本里components、composables、layouts、pages、plugins、utils 这些目录全部平铺在项目根目录时间一久根目录就变成一个大仓库。尤其是团队协作场景新成员进来根本分不清哪个目录是客户端的、哪个是服务端的。Nuxt 4 对此做了非常果断的重构客户端相关代码默认收进 app/ 目录服务端逻辑统一放 server/跨端共享的逻辑放 shared/。我整理过一个对比表迁移时可以直接参考代码类型Nuxt 3 默认位置Nuxt 4 推荐位置说明页面组件pages/app/pages/路由页面约定式路由普通组件components/app/components/自动导入组件组合式函数composables/app/composables/自动导入函数工具函数utils/app/utils/自动导入函数布局layouts/app/layouts/页面布局插件plugins/app/plugins/客户端或服务端插件静态资源public/public/ 或 app/assets/公开文件与构建资源服务端接口server/api/server/api/Nitro 服务端接口共享类型与工具无统一位置shared/可跨端导入这个调整表面看只是“搬家”实际上它改变了我们组织代码块的思维。以前写一个功能组件在 components/请求逻辑在 composables/类型定义可能随手放在 types/ 或者干脆写在组件里。现在有了清晰的边界代码块天然会按运行环境划分客户端相关的进 app/服务端相关的进 server/两边都用的进 shared/。我迁移时的具体做法很简单先建好 app/、server/、shared/ 的骨架然后把原项目对应目录整体移过去再全局替换路径引用。真正让我头疼的不是迁移本身而是迁移后代码块的“回归测试”——页面能跑起来不代表路径都对了很多组件引用的相对路径、图片资源路径在构建时才暴露问题。所以我的建议是迁移完第一件事就是跑一遍nuxt build把构建日志里的每一条警告都当回事。1.2 我理解的“代码块”到底是什么题目里说的代码块不是指编辑器里一段高亮的代码片段而是在 Nuxt 4 这个框架下“可以被独立设计、独立复用、独立加载”的代码单元。它可以是一个 Vue 组件、一个组合式函数、一个工具模块、一个服务端 API 路由也可以是一组配套的缓存策略。我习惯把代码块想象成乐高积木。大的页面是颗粒比较大的底板组件是标准砖块composable 是轴类零件shared 里的工具函数是连接件。好的积木系统有个特点每块积木都有明确的功能能单独拿出来和别的东西组合也能随时替换而不影响整体结构。代码块也是这个道理。一个合格的 Nuxt 4 代码块至少要满足四个标准职责单一、边界清晰、可复用、可优化。职责单一决定了它能不能被理解边界清晰决定了它能不能被移动到正确的位置可复用决定了它值不值得抽出来可优化则决定了它未来能不能被懒加载、缓存或离线化。开发过程中我会反复问自己这段代码放在这里合适吗如果另一个页面也要用我能不能直接引过来如果它只属于某个页面我是不是应该就近存放而不是塞进全局组件库这些问题逼着我把大组件拆小、把请求逻辑抽成函数、把重复类型定义收敛到 shared。整个过程没有高深技巧靠的就是持续重构。2. 高效代码块的组织策略与自动导入2.1 组件与组合式函数边界怎么划组件和组合式函数是 Nuxt 页面里最常出现的两类代码块。我见过很多项目把组件写成“上帝组件”页面顶部是数据请求中间是十几个条件渲染底部是一堆方法。这种组件动辄几百行根本没法复用也没法优化。我的划分思路是把“数据获取”和“交互展示”分开。组件只负责展示和交互数据逻辑放进 composable如果某段数据获取逻辑在多个页面里出现那它就该从组件里抽出来做成一个独立的代码块。举一个实际的例子请求接口获取用户列表。// app/composables/useUserList.ts export function useUserList() { return useAsyncData( user-list, () $fetch(/api/users), { server: true, staleTime: 10 * 1000, } ) }页面里这样用script setup langts const { data: users, pending, error, refresh } useUserList() /script template div div v-ifpending加载中.../div ul v-else-ifusers li v-foruser in users :keyuser.id{{ user.name }}/li /ul p v-else-iferror加载失败/p button clickrefresh刷新/button /div /template这样拆分之后组件变得非常“薄”任何页面想要显示用户列表直接调用useUserList()就行。更关键的是useAsyncData自带的 payload 机制让服务端渲染和客户端水合共用同一份数据既避免了重复请求也减少了首屏闪烁。加一个我在项目中踩过的坑useAsyncData的 key 如果只写死字符串多个请求并发时容易出现数据串号。建议把 API 路径或参数拼到 key 里或者直接依赖 URL 作为默认 key。我在封装通用请求时喜欢写成下面这样// app/composables/useApi.ts export function useApiT(url: string, options: FetchOptions { key?: string } {}) { const key options.key ?? url return useAsyncDataT( key, () $fetchT(url, options), { server: true, getCachedData(key) { const data useNuxtDataT(key) return data.data.value }, } ) }这样基于 URL 自动生成缓存 key同一个接口在多个页面被调用时天然共享一份数据。对于 GET 请求类的接口这几乎是零成本的接口缓存方案。2.2 shared 目录前后端共享的逻辑块Nuxt 4 新增的 shared/ 目录是我最看重的特性之一。在旧版本里一个工具函数如果既要在客户端用、又要在服务端用只能靠人为约定保持“环境无关”。现在 shared/ 从物理上划出了一块安全区放在这里的代码块可以同时被 app/ 和 server/ 导入。我经常放在 shared/ 里的东西有两类类型定义和纯函数工具。// shared/types/order.ts export interface Order { id: string totalAmount: number status: pending | paid | shipped | cancelled createdAt: string }// shared/utils/date.ts export function formatDateTime(isoString: string): string { return new Intl.DateTimeFormat(zh-CN, { year: numeric, month: 2-digit, day: 2-digit, hour: 2-digit, minute: 2-digit, }).format(new Date(isoString)) }通过#shared别名导入非常清晰import type { Order } from #shared/types/orderNode.js 24 的 next: dev 下很多端到端逻辑现在也确实走这套 ES模块安全性也有保障。不是说普通 ws 不行而是#shared带来的语义边界会让代码块的依赖关系变得非常直观。判断一个模块该不该放进 shared/我有个很笨但很有效的标准检查它有没有依赖 window、document、localStorage 这类浏览器全局对象或者 process、eventHandler 这类服务端全局对象。两者都不依赖且确实有跨端使用场景就放进 shared/否则放在 app/ 或 server/ 里更合适。否则一旦在服务端引用了依赖 localStorage 的代码会直接报错这种问题在开发环境不一定会立刻暴露。2.3 基于场景的接口缓存代码块很多人一说到“接口缓存”就想到 Service Worker其实 Nuxt 里的接口缓存有更轻量、更符合 SSR 场景的方案。useAsyncData提供了getCachedData选项可以让我们自定义缓存命中逻辑。以我之前做的一个内部中后台项目为例列表页会频繁切换查询条件请求同一条接口但数据其实一分钟内基本不会变。我给接口请求加了一个基于 Map 的缓存池// app/composables/useCachedFetch.ts const cache new Mapstring, { data: unknown; expiresAt: number }() export function useCachedFetchT(url: string, ttl 60_000) { return useAsyncDataT( url, () $fetchT(url), { server: true, getCachedData(key) { const cached cache.get(key) if (cached cached.expiresAt Date.now()) { return cached.data as T } return undefined }, } ) }封装完成之后接口在 TTL 内重复请求会直接从内存缓存中读数据服务端渲染场景也可以直接用不需要额外引第三方库。这一招对读多写少的页面特别有效。需要额外提醒的是useAsyncData的 payload 默认会序列化到 HTML 中所以千万不要把用户密码、token 这类敏感数据塞进响应里缓存。我们项目里专门约定只有公开接口或被用户主动拉取的列表数据才做缓存涉及隐私的一律关掉。3. 代码块体积与加载性能优化技巧3.1 动态导入与异步组件代码块再整齐如果全部打包进首屏那也是灾难。Nuxt 天然支持路由层面的代码分割一个页面一个 chunk但页面上富交互组件比如代码编辑器、大图表、上传组件依然有可能出现在首屏这时候就要手动拆。Vue 提供了defineAsyncComponent可以很方便地让组件进入异步加载script setup langts import { defineAsyncComponent } from vue const CodeEditor defineAsyncComponent( () import(~/components/CodeEditor.vue) ) /script template div CodeEditor v-ifshow / /div /template在 Nuxt 里更符合习惯的做法是给组件加Lazy前缀。Nuxt 会自动把LazyFoo.vue转换成懒加载组件调用时才会加载对应 chunk。我一般两层配合用外层用Lazy前缀控制是否进入首屏内层用defineAsyncComponent控制真正的资源加载时机。关于这个很多人会忽略一个细节懒加载并不等于“越快越好”。如果某个组件用户几乎一定会用到只是出现位置在首屏下方懒加载反而会导致滚动到那里时有一小段白屏。我的经验是首屏内且关键交互组件正常引入首屏外或低概率使用的再懒加载。性能优化的核心是“减少用户感知的等待”而不是单纯地让初始 bundle 变小。3.2 路由级代码分割与 routeRules 的正确用法Nuxt 基于文件路由天然做了页面级代码分割但是否被正确执行很多时候取决于写法。我见过有同事在页面里直接import一个大模块导致该模块被打进每个页面公共 chunk。正确做法是所有非必选模块都走动态import()让构建工具自动分包。再看看routeRules这算 Nuxt 4 里性价比最高的优化方式之一。它允许我们针对不同路由设置不同的渲染与缓存规则// nuxt.config.ts export default defineNuxtConfig({ routeRules: { /: { prerender: true }, /docs/**: { swr: 3600 }, /reports/**: { isr: 600 }, /api/**: { cache: { maxAge: 60, swr: true } }, }, })什么意思呢swr: 3600表示页面在一小时内重新验证但立即返回缓存isr: 600表示页面静态生成后每 10 分钟重新生成一次。对于那些不需要实时更新的页面这能极大降低服务器渲染代码块的执行频率也变相减少了用户等待时间。我们内部一个报表项目把所有报表路由改成 ISR 之后接口压力直接降了一个数量级。至于manualChunks我的建议是“别轻易动”。Vite 默认分包策略在大多数场景已经很合理强行把手动分包写进配置短期内可能看到首屏体积下降但后续版本升级很容易踩到循环引用或缓存失效的坑。真到了需要细拆的地步优先检查是不是有某个库打进了多个 chunk然后针对那个库单独配置。3.3 离线缓存与代码块版本管理性能优化做到最后一定会碰到“缓存”问题。构建产物里的 JS、CSS 文件名默认带 hash只要文件内容变了文件名就变这天然适合长缓存。配合 Service Worker 的预缓存机制浏览器第一次访问后后续加载基本走本地缓存离线也能打开页面。这里就延伸到热词里很多人问的Nuxt 4 PWA 离线缓存到底怎么配置、接口缓存怎么做。我放在下一节完整写因为操作步骤比较多单独占一个段落更清晰。4. PWA 离线缓存与接口缓存的完整落地4.1 接入 vite-pwa/nuxt 并配置离线缓存Nuxt 4 做 PWA 最顺手的方案是官方生态里的vite-pwa/nuxt模块。它的底层是 Workbox帮我们封装好了预缓存、运行时缓存、更新提示这些逻辑。安装很简单npx nuxi module add vite-pwa模块装好之后在nuxt.config.ts里做基础配置// nuxt.config.ts export default defineNuxtConfig({ modules: [vite-pwa/nuxt], pwa: { registerType: autoUpdate, manifest: { name: 我的 Nuxt 应用, short_name: NuxtApp, description: 基于 Nuxt 4 与 PWA 的离线应用, lang: zh-CN, display: standalone, }, workbox: { globPatterns: [**/*.{js,css,html,ico,png,svg,woff2}], cleanupOutdatedCaches: true, navigateFallback: /, }, }, })workbox.globPatterns决定了哪些文件会被预缓存。默认情况下构建后的 JS 和 CSS 都会带 hash更新后文件名变化旧缓存由于开启了cleanupOutdatedCaches会被自动清理。这一步非常关键否则用户设备上会积压一堆旧的代码块白白浪费存储空间。运行npm run build之后项目根目录会生成sw.jsnuxt.config里 get 不到时可以在构建输出确认。开发环境下默认不启用 SW如果想本地调试需要打开devOptions.enabled。我在开发阶段试过开启结果每次保存代码都会触发一次 SW 更新反而影响热更新体验所以调试完记得关掉。4.2 接口缓存策略离线也要看到数据接口缓存是 PWA 离线体验里最核心的部分。App Shell 预缓存解决了页面框架的离线访问可页面里的数据如果拿不到白屏还是避免不了。好在 Workbox 提供了三种常用运行时缓存策略我们按接口场景选择即可策略行为适用场景CacheFirst先查缓存命中直接返回未命中才请求网络不常变的静态数据、配置信息NetworkFirst先请求网络失败时回退缓存对数据新鲜度敏感但需要离线兜底StaleWhileRevalidate先返回缓存同时后台更新缓存新鲜度要求一般、追求首屏速度我在nuxt.config.ts里给公开接口配了如下规则// nuxt.config.ts export default defineNuxtConfig({ pwa: { workbox: { runtimeCaching: [ { urlPattern: /\/api\/public\/.*/, handler: StaleWhileRevalidate, options: { cacheName: public-api-cache, expiration: { maxEntries: 50, maxAgeSeconds: 60 * 60 * 24, }, }, }, ], }, }, })实际体验下来StaleWhileRevalidate是采访大数据接口的甜点策略。用户点进页面接口数据能秒回后台同时在悄悄刷新缓存下一次访问就是最新数据。但要注意一点这个策略只有在缓存里已经有数据时才能做到离线秒回用户第一次访问页面时依旧依赖网络。想让用户第一次就能离线访问只能在构建期预取某些关键接口或者接受“先联网一次之后离线可用”的现实。还有一个很容易被忽略的点POST 请求默认不适合进运行时缓存。Workbox 匹配请求会把请求方法和 URL 一起判断如果你确实要缓存 POST 接口必须在urlPattern里明确匹配方法否则建议直接给 POST 接口配NetworkOnly避免产生脏数据。4.3 Service Worker 代码块的组织与更新Service Worker 本质上也是一个代码块只是它运行在浏览器与网络之间职责非常特殊。我见过有人把几十个策略全部堆在一个sw.ts里维护起来非常痛苦。更好的做法是让模块处理注册与更新把策略拆成独立配置保持nuxt.config.ts里的workbox尽量简洁。注册逻辑我一般放在插件里// app/plugins/pwa.ts import { registerSW } from virtual:pwa-register const updateSW registerSW({ immediate: true, onNeedRefresh() { const refresh confirm(检测到新版本是否立即刷新) if (refresh) updateSW(true) }, onOfflineReady() { console.log(离线缓存准备完成) }, })registerType: autoUpdate是开箱即用的配置但“自动更新”不是立即生效而是用户下一次刷新页面时启用新的 SW。如果你希望用户无感更新autoUpdate 已经足够如果你要强提示新版本就用上面的onNeedRefresh弹确认框。这个选择取决于业务形态没有绝对正确答案。在调试 Service Worker 时我推荐用 Chrome DevTools 的 Application 面板查看 Cache Storage。经常有同学说“接口明明更新了页面还是旧数据”打开面板一看旧的缓存还在策略没生效。排查思路我放在下一节统一写因为这类问题实在太多。5. 常见问题与排查技巧实录5.1 自动导入失效、组件未找到Nuxt 4 的自动导入依赖.nuxt目录的生成结果。组件移动目录后偶尔会出现 IDE 里引用正常、运行却报“组件未找到”的情况。我遇到时的第一反应是清掉.nuxt缓存停掉 dev server删除.nuxt和node_modules/.cache再重新启动。另一个比较隐蔽的原因是命名冲突。Nuxt 的自动导入规则是“目录名 文件名 导出的变量名”如果app/composables/里导出了一个名叫useApi的函数某个页面又自己定义了一个同名变量编译期很可能不报错运行期却行为诡异。排查时先搜一下全局是否存在同名导出养成给 composable 统一加use前缀、工具函数统一camelCase的习惯能省很多麻烦。5.2 离线时页面白屏、接口报错离线白屏有两种常见情况首页能打开、内页白屏或者页面框架能打开、数据区域空白。内页白屏多数是预缓存遗漏了 Vue Router 动态导入产生的 chunk。第一次在线浏览时浏览器会把 chunk 放进展缓存但如果是没访问过的路由离线时自然加载不到。解决办法是在 Workbox 里把路由对应的页面 chunk 也加进预缓存列表或者接受“离线只保证已访问过的页面可用”这个约束。数据区域空白则基本是接口缓存策略的问题。检查步骤我总结成一个速查表现象可能原因处理方式SW 没注册插件未加载、构建后未刷新检查 Application 面板 Service Workers预缓存列表为空globPatterns 不匹配确认构建产物扩展名是否在列表内接口离线报错未配置 runtimeCaching 或命中非缓存策略检查 urlPattern 是否覆盖目标接口缓存旧数据策略是 CacheFirst 且 TTL 过长调短 maxAgeSeconds 或改为 NetworkFirst调试缓存问题最忌讳直接猜用 DevTools 的 Network 面板看每个请求的 Size 列如果显示from ServiceWorker就能确认走了 SW 缓存如果显示from disk cache那实际是浏览器 HTTP 缓存和 SW 无关。这两个来源经常被混为一谈它们底层逻辑和清理方式完全不一样。5.3 接口缓存污染、数据串号这个问题我在实际项目里踩过必须单独拿出来讲。Service Worker 的缓存是全局共享的同一条 URL 的响应会覆盖保存。如果接口携带用户信息比如返回当前登录用户的订单列表而你又配置了 StaleWhileRevalidate那么用户 A 看到的可能是在某个时刻被缓存下来的用户 B 的数据——这是严重的越权风险。我们的原则很简单带用户维度的私有接口一律 NetworkOnly只在公开接口上做缓存。如果确实有私有接口要兼顾体验把用户 ID 作为 URL 查询参数拼进请求让不同用户的请求命中不同缓存键。但即便如此我还是不建议对私有接口做 SW 缓存因为 PWA 的 shared cache 设计不适合存放这种数据。接口缓存的决策顺序应该是先判断数据是否安全再判断是否新鲜最后才决定用哪种策略。安全永远排在第一位。6. 给团队的三条代码块维护建议6.1 代码块评审清单我自己开发时抽一个代码块之前会先过一遍简短清单这段代码是否会在两个以上地方使用如果只在一个地方用那它应该留在组件内部而不是被全局引用它是否依赖当前页面上下文比如访问了useRoute()、useNuxtApp()这类函数就不适合放进 shared/它是否足够“纯”输入确定、输出确定不触发额外副作用才能保证复用时的稳定性。每次拿到需求我会先花 10 分钟思考代码块的位置再动笔写逻辑。位置错了后面所有优化都是空谈。一个放错位置的代码块就像一块型号不对的积木强行拼上去迟早要拆下来重拼。6.2 命名与目录约定命名看起来是小事但决定了团队长期维护效率。我们的约定是组件统一用 PascalCase普通组件放在app/components/页面专用组件就近放在页面目录下composable 统一use前缀工具函数用 camelCase类型定义用 interface PascalCase跨端共享的放shared/并用#shared别名导入。这套约定执行了半年多最大的变化是新人上手速度明显变快。看代码时只要听到命名基本就能判断它在项目里的角色。命名不是为机器服务的是为半年后还要读代码的自己和同事服务的。6.3 最后的个人经验最后再分享一个我自己的习惯每次把一段逻辑抽成独立代码块之前我都会问自己三个问题——它会在哪端运行它依赖什么上下文它变了会影响谁三个问题能答清楚这个代码块基本就合格了。答不清楚也没关系先写组件内部等代码重复出现第二次、第三次时再抽。过早抽象和过度设计比抽得晚更可怕。