使用正确的数据获取、水合和服务端模式构建 Vue 3 SSR/SSG 应用
Nuxt 3 模式
功能概述
Nuxt 3 模式是一项面向实际任务的技能,主要用于Data 获取;使用 Fetch 调试和缓存请求 SSY 期间使用它;
核心要点
- $fetch 用于组件, 而不是两次获取( 服务器 + 客户端);
- $fetch 用于事件处理者和服务器。
- 它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
使用与执行
使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景,可作为自动化工作流的一部分,也便于后续检查、调整和扩展。从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。
结果检查与注意事项
实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。
Nuxt 3 模式
数据获取
useFetch在服务端渲染(SSR)期间自动去重并缓存请求 — 应在组件中使用,避免使用$fetch(它会在服务端和客户端各执行一次,导致重复请求)$fetch仅适用于事件处理器和服务端路由 — 在中直接调用会导致水合不匹配(hydration mismatch)useFetch在 SSR 期间于服务端执行 — 若需仅在客户端获取数据,请通过process.server进行判断- 当 URL 参数变化但路径不变时,需为
useFetch显式指定key选项;否则缓存将返回陈旧数据 useLazyFetch不会阻塞导航 — 适用于非关键数据,但需主动处理加载中的状态(pending state)
水合陷阱
- 模板中直接使用
Date.now()或Math.random()会导致水合不匹配 — 应在setup中预先计算一次,或使用包裹 - 仅浏览器可用的 API(如
localStorage、window)在 SSR 中会崩溃 — 需包裹在onMounted钩子中,或通过process.client判断执行条件 - 基于仅客户端状态的条件渲染会导致水合不匹配 — 建议使用带 fallback 的
组件 - 对异步数据使用
v-if可能造成错误内容短暂闪烁(flash of wrong content) — 推荐改用v-show或骨架屏(skeleton state)
自动导入
components/目录下的组件支持基于目录结构的自动导入 — 例如components/UI/Button.vue将自动注册为composables/目录下的组合式函数必须以use*命名才能被自动导入 —utils.ts等非use*命名的导出不会被自动导入server/utils/中的工具函数仅在服务端路由中自动导入 — 客户端代码中不可用- 可通过添加
// @ts-nocheck注释或显式导入的方式,按文件禁用自动导入,以避免命名冲突
服务端路由
server/api/目录下的文件自动映射为 API 路由 — 例如server/api/users.get.ts将响应GET /api/users- 方法后缀(如
.get.ts、.post.ts)是定义特定 HTTP 方法处理器所必需的 — 若省略,则该文件将处理所有 HTTP 方法 - 使用
getQuery(event)获取查询参数,使用readBody(event)解析 POST 请求体 — 请勿直接访问event.req - 服务端路由的返回值会自动序列化为 JSON — 如需返回错误,请抛出
createError({ statusCode: 404 })
状态管理
useState具备 SSR 安全性,并可在页面跳转间持久化状态 — 普通ref()在每次页面加载时都会重置useState的 key 必须在整个应用范围内唯一 — 键名冲突将导致不同组件静默共享同一份状态- PINIA Store 在解构时需配合
storeToRefs()使用,以保持响应性 — 否则解构后的值将失去响应性 - 请勿在
useState的默认值中初始化依赖浏览器 API 的状态 — 因其同样会在服务端执行
中间件
middleware/目录下以.global.ts结尾的中间件为全局中间件,会在每个路由上运行 — 执行顺序按文件名字母序排列- 在
definePageMeta中定义的路由中间件将在全局中间件之后执行 — 适合用于特定页面的身份验证检查等场景 - 在中间件中调用
navigateTo()时必须显式return— 若遗漏return,导航将不会生效,流程将继续进入原目标路由 server/middleware/中的中间件作用于所有服务端请求(包括 API 路由)
配置
runtimeConfig用于存放服务端密钥,runtimeConfig.public用于存放可安全暴露至客户端的配置项 — 环境变量可通过NUXT_前缀进行覆盖app.config.ts用于定义构建时即确定、无需环境变量介入的配置 — 其内容会被打包进应用中- 修改
nuxt.config.ts需重启开发服务器 — 修改app.config.ts支持热更新(hot-reload)
SEO 与元信息
useSeoMeta用于设置标准 meta 标签 — 提供类型安全,并自动处理og:/twitter:等前缀useHead用于插入自定义标签、脚本及链接 — 更加灵活,但对 meta 名称无类型保护definePageMeta中声明的元信息为静态内容 — 动态值应在setup中使用useSeoMetanuxt.config中的titleTemplate用于统一标题格式 — 推荐采用%s - My Site模式
插件
- 插件在应用实例创建前运行 — 如需在创建后执行逻辑,请使用
nuxtApp.hook('app:created') - 插件中通过
provide注入的值可通过useNuxtApp()访问 — 但通常推荐优先使用组合式函数(composables) - 插件执行顺序:带数字前缀的文件(如
01.plugin.ts)优先执行,其余按字母序 — 若存在依赖关系,需通过显式命名控制顺序 - 仅客户端插件需以
.client.ts为后缀;仅服务端插件需以.server.ts为后缀
构建与部署
nuxt generate生成静态文件 — 但 API 路由在无服务端支持的情况下无法工作nuxt.build生成服务端产物 — 部署时应上传整个.output目录- 通过
routeRules启用增量静态再生(ISR):例如'/blog/**': { isr: 3600 }表示页面缓存 1 小时 - 预渲染特定路由:例如
routeRules: { '/about': { prerender: true } }表示在构建时生成该路由的静态 HTML
热门AI工具
相关专题
Vite项目打包部署专题汇集生产构建、产物预览、输出目录、资源路径、Nginx与GitHub Pages部署及常见白屏和路由404问题的已审核文章,帮助读者完成上线流程。
0
2026.10.28
Vite搭配Vue.js专题汇集创建Vue 3项目、配置开发环境、路径别名、Vue插件、代理、多环境构建与调试的已审核文章,帮助读者完成从初始化到日常开发的配置。
0
2026.10.28
Vite项目目录专题汇集入口文件、src源码、public静态资源、路径别名、项目根目录和构建输出目录相关的已审核文章,帮助读者理解各文件夹的用途与引用方式。
0
2026.10.28
本专题介绍Gradle插件开发的基本流程,涵盖插件类编写、自定义任务注册、扩展参数设计和插件应用方法,帮助你理解插件如何组织构建逻辑,减少多个项目之间的重复配置。
0
2026.10.22
本专题介绍Gradle Wrapper的基本作用,涵盖文件组成、生成方法、版本配置和任务调用,帮助你理解项目如何使用指定的Gradle版本,减少不同开发环境带来的构建差异。
0
2026.10.22
本专题整理Golangci-lint常用Linters的用途与配置方法,覆盖错误处理、无效代码、安全、复杂度、命名和依赖检查,帮助项目合理选规则。
0
2026.10.22
本专题介绍Gradle Java项目构建方法,涵盖Java插件配置、依赖声明、源码编译、测试执行和打包检查,帮助你理解各阶段的任务关系,逐步完成项目构建。
0
2026.10.22
本专题汇总PHP常见时间戳漏洞,包括2038年溢出、时区漂移、时间戳伪造、重放攻击、时间盲注与日志审计失效等,并给出升级64位环境、使用 DateTimeImmutable、统一UTC、严格超时校验、预处理绑定、hash_equals 比对等修复方案,帮助开发者快速排查和加固时间相关代码。
0
2026.10.22
本专题聚焦Golangci-lint YAML配置文件,讲清运行参数、规则启停、目录排除、问题过滤及严重级别设置,便于团队统一检查标准。
0
2026.10.22
热门下载
精品课程
共6课时 | 12.1万人学习
共79课时 | 161.6万人学习
共6课时 | 54.7万人学习
最新文章