Nuxt4阶段六工程化与进阶 —— 模块、中间件、插件、TS 与测试学习目标会用 Nuxt Modules、路由中间件、插件理解 Nuxt 4 TypeScript 分层能写基础测试与统一错误处理。预计时间1–2 周前置完成阶段一至五。本阶段产出带登录守卫的后台、一个实用插件、基础测试用例。1. Nuxt Modules扩展能力的官方方式模块能改构建、加目录约定、注册组件与 composables。1.1 安装与注册pnpmaddnuxt/ui# 或 Tailwindpnpm add nuxtjs/tailwindcsspnpmaddvueuse/nuxtpnpmaddnuxtjs/color-mode// nuxt.config.tsexportdefaultdefineNuxtConfig({modules:[nuxt/ui,vueuse/nuxt,nuxtjs/color-mode,],colorMode:{classSuffix:,},})浏览生态https://nuxt.com/modules1.2 初学者建议组合模块用途nuxt/ui或 TailwindUI / 样式vueuse/nuxt超全的 composablesnuxtjs/color-mode亮暗色pinia/nuxt状态阶段三nuxt/image图片阶段五nuxt/test-utils测试nuxtjs/i18n国际化阶段八可用不必一次装全按需添加。2. 路由中间件页面级鉴权放在app/middleware/。2.1 匿名中间件局部使用app/middleware/auth.tsexportdefaultdefineNuxtRouteMiddleware(async(to){const{data:user}awaituseFetch(/api/auth/me,{key:auth-me,// 避免重复导航时刷屏错误可按需调整})if(!user.value){returnnavigateTo({path:/login,query:{redirect:to.fullPath},})}})页面启用definePageMeta({middleware:auth,layout:admin,})2.2 全局中间件文件名加.global.ts例如app/middleware/analytics.global.tsexportdefaultdefineNuxtRouteMiddleware((to){if(import.meta.client){console.log([nav],to.fullPath)}})每个路由都会跑——保持逻辑轻量。2.3 中间件执行顺序全局中间件文件名排序布局/页面定义的中间件页面渲染2.4 登录页示例app/pages/login.vuescriptsetuplangtsdefinePageMeta({layout:false})constrouteuseRoute()constusernameref(admin)constpasswordref(123456)consterrorMsgref()asyncfunctiononSubmit(){errorMsg.valuetry{await$fetch(/api/auth/login,{method:POST,body:{username:username.value,password:password.value},})awaitnavigateTo((route.query.redirectasstring)||/admin)}catch(e:any){errorMsg.valuee?.data?.message||登录失败}}/scripttemplateformsubmit.preventonSubmith1登录/h1inputv-modelusernameplaceholder用户名/inputv-modelpasswordtypepasswordplaceholder密码/pv-iferrorMsg{{ errorMsg }}/pbuttontypesubmit登录/button/form/template/admin加middleware: auth未登录会被踢回/login。3. 插件 Plugins用于初始化第三方库、注入全局方法。3.1 客户端插件app/plugins/hello.client.ts仅浏览器exportdefaultdefineNuxtPlugin((){return{provide:{hello:(name:string)Hello,${name}!,},}})使用const{$hello}useNuxtApp()console.log($hello(Nuxt))3.2 服务端插件app/plugins/server-init.server.ts仅 SSR/服务端运行。3.3 通用插件无.client/.server后缀则两端都跑——注意不要碰window。3.4 Vue 插件示例假想exportdefaultdefineNuxtPlugin((nuxtApp){// nuxtApp.vueApp.use(SomeVuePlugin)})排序可用文件名数字前缀01.foo.ts、02.bar.ts。4. TypeScript 与 Nuxt 4 项目分离Nuxt 4 为不同上下文准备了更清晰的类型边界上下文大致范围app页面、组件、composables、插件serverserver/**sharedshared/**node / builder配置与构建相关好处不会在前端代码里「误用」仅服务端 API 还不报错或反过来。实践建议公共类型放shared/或shared/types为runtimeConfig补类型可通过配置自动推导或扩展接口打开严格模式逐步修类型错误实验性Typed Routes让navigateTo(/blog/1)等有路径提示。可在文档中开启experimental.typedPages以当前版本文档为准。5. 错误处理工程化5.1 全局error.vue见阶段五确保存在并样式可读。5.2 组件内const{error}awaituseFetch(/api/posts)5.3 主动抛错throwcreateError({statusCode:403,statusMessage:Forbidden})5.4 钩子了解// pluginsexportdefaultdefineNuxtPlugin((nuxtApp){nuxtApp.hook(vue:error,(err){console.error(vue:error,err)})})6. 测试入门pnpmadd-Dnuxt/test-utils vitest vue/test-utils happy-domnuxt.config.ts可按nuxt/test-utils文档添加配置。示例vitest.config.tsimport{defineVitestConfig}fromnuxt/test-utils/configexportdefaultdefineVitestConfig({test:{environment:nuxt,},})组件测试示例// tests/PostCard.spec.tsimport{describe,it,expect}fromvitestimport{mountSuspended}fromnuxt/test-utils/runtimeimportBlogPostCardfrom~/components/blog/PostCard.vuedescribe(BlogPostCard,(){it(renders title,async(){constwrapperawaitmountSuspended(BlogPostCard,{props:{id:1,title:Hello,excerpt:World},})expect(wrapper.text()).toContain(Hello)})})API 测试可对 handler 做单元测试或用$fetch打setup后的测试服务器见官方 Testing 指南。package.json{scripts:{test:vitest run,test:watch:vitest}}7. 代码组织最佳实践中型项目app/ components/ blog/ # 按领域分 ui/ # 通用 UI composables/ useAuth.ts useApi.ts middleware/ pages/ layouts/ plugins/ server/ api/ auth/ posts/ todos/ utils/ middleware/ shared/ types/ utils/ # 纯函数、无 Node/浏览器依赖原则页面保持瘦数据获取 拼装组件可复用逻辑进 composables可复用 UI 进 components服务端 IO 不进 composables除非包$fetch8. 环境与质量工具可选但推荐pnpmadd-Deslint nuxt/eslint# 按模块文档初始化Prettier、Husky、lint-staged 可按团队习惯加。学习阶段有 ESLint 即可。9. 暗色模式小练习若装了nuxtjs/color-modescriptsetuplangtsconstcolorModeuseColorMode()/scripttemplatebuttonclickcolorMode.preference colorMode.value dark ? light : dark当前{{ colorMode.value }}/button/templateCSS:root{color-scheme:light;}.dark{color-scheme:dark;background:#111;color:#eee;}10. 本阶段验收清单至少安装并配置 2 个 Nuxt 模块auth中间件保护/admin未登录跳转/login写过一个.client插件并provide方法存在友好的error.vue加分Vitest 至少一个组件测试通过加分shared/types被 app 与 server 同时引用加分接入 color-mode11. 常见坑中间件里错误使用useFetch导致循环登录页不要挂auth中间件失败时注意别重定向到自己。插件里直接碰window用.client后缀或import.meta.client判断。测试环境与运行时不一致优先用官方nuxt/test-utils的environment: nuxt。全局中间件太重每个导航都跑别在里面狂打 API。12. 阶段总结你已经掌握Modules 扩展方式路由中间件鉴权流插件注入与客户端/服务端拆分TS 分层意识、测试与错误页下一篇阶段七 —— 构建、环境变量、Vercel/Docker/Node 部署与简易 CI。参考链接ModulesMiddlewarePluginsTestingNuxt 4 AnnouncementTS 等
Nuxt4阶段六工程化与进阶 —— 模块、中间件、插件、TS 与测试学习目标会用 Nuxt Modules、路由中间件、插件理解 Nuxt 4 TypeScript 分层能写基础测试与统一错误处理。预计时间1–2 周前置完成阶段一至五。本阶段产出带登录守卫的后台、一个实用插件、基础测试用例。1. Nuxt Modules扩展能力的官方方式模块能改构建、加目录约定、注册组件与 composables。1.1 安装与注册pnpmaddnuxt/ui# 或 Tailwindpnpm add nuxtjs/tailwindcsspnpmaddvueuse/nuxtpnpmaddnuxtjs/color-mode// nuxt.config.tsexportdefaultdefineNuxtConfig({modules:[nuxt/ui,vueuse/nuxt,nuxtjs/color-mode,],colorMode:{classSuffix:,},})浏览生态https://nuxt.com/modules1.2 初学者建议组合模块用途nuxt/ui或 TailwindUI / 样式vueuse/nuxt超全的 composablesnuxtjs/color-mode亮暗色pinia/nuxt状态阶段三nuxt/image图片阶段五nuxt/test-utils测试nuxtjs/i18n国际化阶段八可用不必一次装全按需添加。2. 路由中间件页面级鉴权放在app/middleware/。2.1 匿名中间件局部使用app/middleware/auth.tsexportdefaultdefineNuxtRouteMiddleware(async(to){const{data:user}awaituseFetch(/api/auth/me,{key:auth-me,// 避免重复导航时刷屏错误可按需调整})if(!user.value){returnnavigateTo({path:/login,query:{redirect:to.fullPath},})}})页面启用definePageMeta({middleware:auth,layout:admin,})2.2 全局中间件文件名加.global.ts例如app/middleware/analytics.global.tsexportdefaultdefineNuxtRouteMiddleware((to){if(import.meta.client){console.log([nav],to.fullPath)}})每个路由都会跑——保持逻辑轻量。2.3 中间件执行顺序全局中间件文件名排序布局/页面定义的中间件页面渲染2.4 登录页示例app/pages/login.vuescriptsetuplangtsdefinePageMeta({layout:false})constrouteuseRoute()constusernameref(admin)constpasswordref(123456)consterrorMsgref()asyncfunctiononSubmit(){errorMsg.valuetry{await$fetch(/api/auth/login,{method:POST,body:{username:username.value,password:password.value},})awaitnavigateTo((route.query.redirectasstring)||/admin)}catch(e:any){errorMsg.valuee?.data?.message||登录失败}}/scripttemplateformsubmit.preventonSubmith1登录/h1inputv-modelusernameplaceholder用户名/inputv-modelpasswordtypepasswordplaceholder密码/pv-iferrorMsg{{ errorMsg }}/pbuttontypesubmit登录/button/form/template/admin加middleware: auth未登录会被踢回/login。3. 插件 Plugins用于初始化第三方库、注入全局方法。3.1 客户端插件app/plugins/hello.client.ts仅浏览器exportdefaultdefineNuxtPlugin((){return{provide:{hello:(name:string)Hello,${name}!,},}})使用const{$hello}useNuxtApp()console.log($hello(Nuxt))3.2 服务端插件app/plugins/server-init.server.ts仅 SSR/服务端运行。3.3 通用插件无.client/.server后缀则两端都跑——注意不要碰window。3.4 Vue 插件示例假想exportdefaultdefineNuxtPlugin((nuxtApp){// nuxtApp.vueApp.use(SomeVuePlugin)})排序可用文件名数字前缀01.foo.ts、02.bar.ts。4. TypeScript 与 Nuxt 4 项目分离Nuxt 4 为不同上下文准备了更清晰的类型边界上下文大致范围app页面、组件、composables、插件serverserver/**sharedshared/**node / builder配置与构建相关好处不会在前端代码里「误用」仅服务端 API 还不报错或反过来。实践建议公共类型放shared/或shared/types为runtimeConfig补类型可通过配置自动推导或扩展接口打开严格模式逐步修类型错误实验性Typed Routes让navigateTo(/blog/1)等有路径提示。可在文档中开启experimental.typedPages以当前版本文档为准。5. 错误处理工程化5.1 全局error.vue见阶段五确保存在并样式可读。5.2 组件内const{error}awaituseFetch(/api/posts)5.3 主动抛错throwcreateError({statusCode:403,statusMessage:Forbidden})5.4 钩子了解// pluginsexportdefaultdefineNuxtPlugin((nuxtApp){nuxtApp.hook(vue:error,(err){console.error(vue:error,err)})})6. 测试入门pnpmadd-Dnuxt/test-utils vitest vue/test-utils happy-domnuxt.config.ts可按nuxt/test-utils文档添加配置。示例vitest.config.tsimport{defineVitestConfig}fromnuxt/test-utils/configexportdefaultdefineVitestConfig({test:{environment:nuxt,},})组件测试示例// tests/PostCard.spec.tsimport{describe,it,expect}fromvitestimport{mountSuspended}fromnuxt/test-utils/runtimeimportBlogPostCardfrom~/components/blog/PostCard.vuedescribe(BlogPostCard,(){it(renders title,async(){constwrapperawaitmountSuspended(BlogPostCard,{props:{id:1,title:Hello,excerpt:World},})expect(wrapper.text()).toContain(Hello)})})API 测试可对 handler 做单元测试或用$fetch打setup后的测试服务器见官方 Testing 指南。package.json{scripts:{test:vitest run,test:watch:vitest}}7. 代码组织最佳实践中型项目app/ components/ blog/ # 按领域分 ui/ # 通用 UI composables/ useAuth.ts useApi.ts middleware/ pages/ layouts/ plugins/ server/ api/ auth/ posts/ todos/ utils/ middleware/ shared/ types/ utils/ # 纯函数、无 Node/浏览器依赖原则页面保持瘦数据获取 拼装组件可复用逻辑进 composables可复用 UI 进 components服务端 IO 不进 composables除非包$fetch8. 环境与质量工具可选但推荐pnpmadd-Deslint nuxt/eslint# 按模块文档初始化Prettier、Husky、lint-staged 可按团队习惯加。学习阶段有 ESLint 即可。9. 暗色模式小练习若装了nuxtjs/color-modescriptsetuplangtsconstcolorModeuseColorMode()/scripttemplatebuttonclickcolorMode.preference colorMode.value dark ? light : dark当前{{ colorMode.value }}/button/templateCSS:root{color-scheme:light;}.dark{color-scheme:dark;background:#111;color:#eee;}10. 本阶段验收清单至少安装并配置 2 个 Nuxt 模块auth中间件保护/admin未登录跳转/login写过一个.client插件并provide方法存在友好的error.vue加分Vitest 至少一个组件测试通过加分shared/types被 app 与 server 同时引用加分接入 color-mode11. 常见坑中间件里错误使用useFetch导致循环登录页不要挂auth中间件失败时注意别重定向到自己。插件里直接碰window用.client后缀或import.meta.client判断。测试环境与运行时不一致优先用官方nuxt/test-utils的environment: nuxt。全局中间件太重每个导航都跑别在里面狂打 API。12. 阶段总结你已经掌握Modules 扩展方式路由中间件鉴权流插件注入与客户端/服务端拆分TS 分层意识、测试与错误页下一篇阶段七 —— 构建、环境变量、Vercel/Docker/Node 部署与简易 CI。参考链接ModulesMiddlewarePluginsTestingNuxt 4 AnnouncementTS 等
