[{"data":1,"prerenderedAt":3427},["ShallowReactive",2],{"article-/topics/nuxt/nuxt-ui-component-library-guide":3,"related-nuxt":645,"content-query-AcGiCm8Wjo":2941},{"_path":4,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":8,"description":9,"date":10,"topic":5,"author":11,"tags":12,"image":18,"imageQuery":19,"pexelsPhotoId":20,"pexelsUrl":21,"featured":6,"readingTime":22,"body":23,"_type":639,"_id":640,"_source":641,"_file":642,"_stem":643,"_extension":644},"/topics/nuxt/nuxt-ui-component-library-guide","nuxt",false,"","Nuxt UI 组件库完整指南：从快速搭建到可维护的产品级页面系统","系统讲清 Nuxt UI 的定位、主题定制、表单与反馈组件、与 Nuxt 项目结构的配合方式，以及什么时候适合用它，什么时候不该硬上。","2026-04-06","HTMLPAGE 团队",[13,14,15,16,17],"Nuxt UI","组件库","Nuxt","主题定制","表单设计","/images/topics/nuxt/nuxt-ui-component-library-guide.jpg","ui component design system laptop workspace",8284731,"https://www.pexels.com/photo/person-using-laptop-8284731/",14,{"type":24,"children":25,"toc":621},"root",[26,35,41,46,61,72,78,83,204,209,215,220,225,248,253,259,264,283,288,301,306,312,317,322,340,345,363,369,374,392,397,403,408,426,431,449,455,536,542,549,554,560,565,571,576,581],{"type":27,"tag":28,"props":29,"children":31},"element","h2",{"id":30},"nuxt-ui-组件库完整指南",[32],{"type":33,"value":34},"text","Nuxt UI 组件库完整指南",{"type":27,"tag":36,"props":37,"children":38},"p",{},[39],{"type":33,"value":40},"Nuxt UI 的价值，不是“多一个组件库”，而是它把 Nuxt 项目的页面搭建、主题变量、表单交互和产品层组件做了更贴近 Nuxt 生态的整合。",{"type":27,"tag":36,"props":42,"children":43},{},[44],{"type":33,"value":45},"但很多团队第一次用 Nuxt UI，会很快踩进两个坑：",{"type":27,"tag":47,"props":48,"children":49},"ul",{},[50,56],{"type":27,"tag":51,"props":52,"children":53},"li",{},[54],{"type":33,"value":55},"把它当“现成后台模板”，结果项目风格越来越像默认站。",{"type":27,"tag":51,"props":57,"children":58},{},[59],{"type":33,"value":60},"什么需求都往组件 props 上压，导致后期定制越来越难。",{"type":27,"tag":36,"props":62,"children":63},{},[64,66],{"type":33,"value":65},"这篇文章的重点不是把文档重写一遍，而是回答一个更实际的问题：",{"type":27,"tag":67,"props":68,"children":69},"strong",{},[70],{"type":33,"value":71},"Nuxt UI 什么时候能帮你加速，什么时候会拖慢你。",{"type":27,"tag":28,"props":73,"children":75},{"id":74},"_1-nuxt-ui-最适合的项目不是任何-nuxt-项目",[76],{"type":33,"value":77},"1. Nuxt UI 最适合的项目，不是“任何 Nuxt 项目”",{"type":27,"tag":36,"props":79,"children":80},{},[81],{"type":33,"value":82},"Nuxt UI 更适合这几类场景：",{"type":27,"tag":84,"props":85,"children":86},"table",{},[87,111],{"type":27,"tag":88,"props":89,"children":90},"thead",{},[91],{"type":27,"tag":92,"props":93,"children":94},"tr",{},[95,101,106],{"type":27,"tag":96,"props":97,"children":98},"th",{},[99],{"type":33,"value":100},"场景",{"type":27,"tag":96,"props":102,"children":103},{},[104],{"type":33,"value":105},"适配度",{"type":27,"tag":96,"props":107,"children":108},{},[109],{"type":33,"value":110},"原因",{"type":27,"tag":112,"props":113,"children":114},"tbody",{},[115,134,151,168,186],{"type":27,"tag":92,"props":116,"children":117},{},[118,124,129],{"type":27,"tag":119,"props":120,"children":121},"td",{},[122],{"type":33,"value":123},"内容站与文档站",{"type":27,"tag":119,"props":125,"children":126},{},[127],{"type":33,"value":128},"高",{"type":27,"tag":119,"props":130,"children":131},{},[132],{"type":33,"value":133},"组件、表单、布局需求较标准",{"type":27,"tag":92,"props":135,"children":136},{},[137,142,146],{"type":27,"tag":119,"props":138,"children":139},{},[140],{"type":33,"value":141},"SaaS 控制台",{"type":27,"tag":119,"props":143,"children":144},{},[145],{"type":33,"value":128},{"type":27,"tag":119,"props":147,"children":148},{},[149],{"type":33,"value":150},"反馈、筛选、弹层、表单组件成熟",{"type":27,"tag":92,"props":152,"children":153},{},[154,159,163],{"type":27,"tag":119,"props":155,"children":156},{},[157],{"type":33,"value":158},"MVP 验证项目",{"type":27,"tag":119,"props":160,"children":161},{},[162],{"type":33,"value":128},{"type":27,"tag":119,"props":164,"children":165},{},[166],{"type":33,"value":167},"能快速搭骨架",{"type":27,"tag":92,"props":169,"children":170},{},[171,176,181],{"type":27,"tag":119,"props":172,"children":173},{},[174],{"type":33,"value":175},"高度品牌化营销官网",{"type":27,"tag":119,"props":177,"children":178},{},[179],{"type":33,"value":180},"中",{"type":27,"tag":119,"props":182,"children":183},{},[184],{"type":33,"value":185},"需要较多视觉定制",{"type":27,"tag":92,"props":187,"children":188},{},[189,194,199],{"type":27,"tag":119,"props":190,"children":191},{},[192],{"type":33,"value":193},"强交互可视化产品",{"type":27,"tag":119,"props":195,"children":196},{},[197],{"type":33,"value":198},"中低",{"type":27,"tag":119,"props":200,"children":201},{},[202],{"type":33,"value":203},"复杂交互通常要自定义",{"type":27,"tag":36,"props":205,"children":206},{},[207],{"type":33,"value":208},"所以不要先问“Nuxt UI 好不好”，要先问“我的页面复杂度和品牌要求是否适合”。",{"type":27,"tag":28,"props":210,"children":212},{"id":211},"_2-真正应该优先学的是主题层而不是组件清单",[213],{"type":33,"value":214},"2. 真正应该优先学的是主题层，而不是组件清单",{"type":27,"tag":36,"props":216,"children":217},{},[218],{"type":33,"value":219},"组件库用久了都会遇到一个问题：组件很多，但风格不统一。",{"type":27,"tag":36,"props":221,"children":222},{},[223],{"type":33,"value":224},"Nuxt UI 更值得优先建立的是主题层：",{"type":27,"tag":47,"props":226,"children":227},{},[228,233,238,243],{"type":27,"tag":51,"props":229,"children":230},{},[231],{"type":33,"value":232},"颜色变量",{"type":27,"tag":51,"props":234,"children":235},{},[236],{"type":33,"value":237},"间距体系",{"type":27,"tag":51,"props":239,"children":240},{},[241],{"type":33,"value":242},"圆角与阴影",{"type":27,"tag":51,"props":244,"children":245},{},[246],{"type":33,"value":247},"标题、正文、标签文字层级",{"type":27,"tag":36,"props":249,"children":250},{},[251],{"type":33,"value":252},"如果主题没先定住，组件用得越多，页面越像临时拼出来的。",{"type":27,"tag":28,"props":254,"children":256},{"id":255},"_3-组件使用策略先搭公共模式再写业务页面",[257],{"type":33,"value":258},"3. 组件使用策略：先搭公共模式，再写业务页面",{"type":27,"tag":36,"props":260,"children":261},{},[262],{"type":33,"value":263},"更稳的顺序是：",{"type":27,"tag":265,"props":266,"children":267},"ol",{},[268,273,278],{"type":27,"tag":51,"props":269,"children":270},{},[271],{"type":33,"value":272},"先定义页面级基础模式，如按钮、卡片、表单项、空状态。",{"type":27,"tag":51,"props":274,"children":275},{},[276],{"type":33,"value":277},"再把这些模式映射到 Nuxt UI 组件能力。",{"type":27,"tag":51,"props":279,"children":280},{},[281],{"type":33,"value":282},"最后才进入业务页拼装。",{"type":27,"tag":36,"props":284,"children":285},{},[286],{"type":33,"value":287},"例如表单层可以先抽成统一配置：",{"type":27,"tag":289,"props":290,"children":295},"pre",{"className":291,"code":293,"language":294,"meta":7},[292],"language-ts","export const formTone = {\n  input: 'w-full',\n  label: 'text-sm font-medium',\n  error: 'text-red-600 text-xs mt-1',\n}\n","ts",[296],{"type":27,"tag":297,"props":298,"children":299},"code",{"__ignoreMap":7},[300],{"type":33,"value":293},{"type":27,"tag":36,"props":302,"children":303},{},[304],{"type":33,"value":305},"这比在每个页面里单独写一堆类名更可维护。",{"type":27,"tag":28,"props":307,"children":309},{"id":308},"_4-一个常见失败案例为了快把业务逻辑塞进组件层",[310],{"type":33,"value":311},"4. 一个常见失败案例：为了“快”，把业务逻辑塞进组件层",{"type":27,"tag":36,"props":313,"children":314},{},[315],{"type":33,"value":316},"很多团队会把加载态、权限判断、接口请求、空状态全塞进单个组件里，觉得这样页面最省事。",{"type":27,"tag":36,"props":318,"children":319},{},[320],{"type":33,"value":321},"结果是：",{"type":27,"tag":47,"props":323,"children":324},{},[325,330,335],{"type":27,"tag":51,"props":326,"children":327},{},[328],{"type":33,"value":329},"组件职责越来越重。",{"type":27,"tag":51,"props":331,"children":332},{},[333],{"type":33,"value":334},"同类页面稍微改一点就得复制组件。",{"type":27,"tag":51,"props":336,"children":337},{},[338],{"type":33,"value":339},"UI 库升级后回归范围非常大。",{"type":27,"tag":36,"props":341,"children":342},{},[343],{"type":33,"value":344},"更好的拆法是：",{"type":27,"tag":47,"props":346,"children":347},{},[348,353,358],{"type":27,"tag":51,"props":349,"children":350},{},[351],{"type":33,"value":352},"组件只负责视觉与交互。",{"type":27,"tag":51,"props":354,"children":355},{},[356],{"type":33,"value":357},"composable 负责状态与请求。",{"type":27,"tag":51,"props":359,"children":360},{},[361],{"type":33,"value":362},"页面层负责拼装业务流程。",{"type":27,"tag":28,"props":364,"children":366},{"id":365},"_5-表单与反馈组件是-nuxt-ui-最值得利用的区域",[367],{"type":33,"value":368},"5. 表单与反馈组件，是 Nuxt UI 最值得利用的区域",{"type":27,"tag":36,"props":370,"children":371},{},[372],{"type":33,"value":373},"Nuxt UI 的真实收益，通常出现在下面这些高频模块：",{"type":27,"tag":47,"props":375,"children":376},{},[377,382,387],{"type":27,"tag":51,"props":378,"children":379},{},[380],{"type":33,"value":381},"输入、选择、校验反馈。",{"type":27,"tag":51,"props":383,"children":384},{},[385],{"type":33,"value":386},"Drawer、Modal、Popover。",{"type":27,"tag":51,"props":388,"children":389},{},[390],{"type":33,"value":391},"Alert、Toast、Badge、Empty state。",{"type":27,"tag":36,"props":393,"children":394},{},[395],{"type":33,"value":396},"这些能力能把 MVP 和产品化页面之间的差距快速拉近。",{"type":27,"tag":28,"props":398,"children":400},{"id":399},"_6-什么时候不该继续硬用-nuxt-ui",[401],{"type":33,"value":402},"6. 什么时候不该继续“硬用 Nuxt UI”",{"type":27,"tag":36,"props":404,"children":405},{},[406],{"type":33,"value":407},"以下情况要提前停下来评估：",{"type":27,"tag":47,"props":409,"children":410},{},[411,416,421],{"type":27,"tag":51,"props":412,"children":413},{},[414],{"type":33,"value":415},"设计语言与默认组件视觉差距很大。",{"type":27,"tag":51,"props":417,"children":418},{},[419],{"type":33,"value":420},"项目大量依赖自定义图形和复杂交互。",{"type":27,"tag":51,"props":422,"children":423},{},[424],{"type":33,"value":425},"同一组件需要出现太多业务变体。",{"type":27,"tag":36,"props":427,"children":428},{},[429],{"type":33,"value":430},"这时更好的策略通常是：",{"type":27,"tag":265,"props":432,"children":433},{},[434,439,444],{"type":27,"tag":51,"props":435,"children":436},{},[437],{"type":33,"value":438},"保留 Nuxt UI 做基础表单与反馈。",{"type":27,"tag":51,"props":440,"children":441},{},[442],{"type":33,"value":443},"把高品牌化区域改成自定义组件。",{"type":27,"tag":51,"props":445,"children":446},{},[447],{"type":33,"value":448},"逐步沉淀你自己的业务组件层。",{"type":27,"tag":28,"props":450,"children":452},{"id":451},"_7-上线前-checklist",[453],{"type":33,"value":454},"7. 上线前 Checklist",{"type":27,"tag":47,"props":456,"children":459},{"className":457},[458],"contains-task-list",[460,473,482,491,500,509,518,527],{"type":27,"tag":51,"props":461,"children":464},{"className":462},[463],"task-list-item",[465,471],{"type":27,"tag":466,"props":467,"children":470},"input",{"disabled":468,"type":469},true,"checkbox",[],{"type":33,"value":472}," 已先定义主题变量，再大规模使用组件。",{"type":27,"tag":51,"props":474,"children":476},{"className":475},[463],[477,480],{"type":27,"tag":466,"props":478,"children":479},{"disabled":468,"type":469},[],{"type":33,"value":481}," 通用按钮、卡片、表单模式已统一。",{"type":27,"tag":51,"props":483,"children":485},{"className":484},[463],[486,489],{"type":27,"tag":466,"props":487,"children":488},{"disabled":468,"type":469},[],{"type":33,"value":490}," 业务逻辑没有塞进基础 UI 组件层。",{"type":27,"tag":51,"props":492,"children":494},{"className":493},[463],[495,498],{"type":27,"tag":466,"props":496,"children":497},{"disabled":468,"type":469},[],{"type":33,"value":499}," 表单、弹层、反馈组件已做统一交互规则。",{"type":27,"tag":51,"props":501,"children":503},{"className":502},[463],[504,507],{"type":27,"tag":466,"props":505,"children":506},{"disabled":468,"type":469},[],{"type":33,"value":508}," 高品牌化页面已评估是否需要自定义组件。",{"type":27,"tag":51,"props":510,"children":512},{"className":511},[463],[513,516],{"type":27,"tag":466,"props":514,"children":515},{"disabled":468,"type":469},[],{"type":33,"value":517}," 组件封装边界明确，可升级可替换。",{"type":27,"tag":51,"props":519,"children":521},{"className":520},[463],[522,525],{"type":27,"tag":466,"props":523,"children":524},{"disabled":468,"type":469},[],{"type":33,"value":526}," 深色模式、移动端和空状态已验证。",{"type":27,"tag":51,"props":528,"children":530},{"className":529},[463],[531,534],{"type":27,"tag":466,"props":532,"children":533},{"disabled":468,"type":469},[],{"type":33,"value":535}," 已准备 Nuxt UI 升级后的回归清单。",{"type":27,"tag":28,"props":537,"children":539},{"id":538},"faq",[540],{"type":33,"value":541},"FAQ",{"type":27,"tag":543,"props":544,"children":546},"h3",{"id":545},"nuxt-ui-适合做官网吗",[547],{"type":33,"value":548},"Nuxt UI 适合做官网吗？",{"type":27,"tag":36,"props":550,"children":551},{},[552],{"type":33,"value":553},"可以，但更适合结构稳定、交互标准化的官网。高度品牌化的营销站通常还需要额外定制。",{"type":27,"tag":543,"props":555,"children":557},{"id":556},"它能替代完整设计系统吗",[558],{"type":33,"value":559},"它能替代完整设计系统吗？",{"type":27,"tag":36,"props":561,"children":562},{},[563],{"type":33,"value":564},"不能。它能加速你搭建系统，但设计系统的变量、命名和治理仍然要自己建立。",{"type":27,"tag":543,"props":566,"children":568},{"id":567},"什么时候该抽业务组件层",[569],{"type":33,"value":570},"什么时候该抽业务组件层？",{"type":27,"tag":36,"props":572,"children":573},{},[574],{"type":33,"value":575},"当同一个 UI 模式在 3 个以上页面复用，并且开始出现业务判断时，就该考虑抽象。",{"type":27,"tag":28,"props":577,"children":579},{"id":578},"延伸阅读",[580],{"type":33,"value":578},{"type":27,"tag":47,"props":582,"children":583},{},[584,594,603,612],{"type":27,"tag":51,"props":585,"children":586},{},[587],{"type":27,"tag":588,"props":589,"children":591},"a",{"href":590},"/topics/nuxt/nuxt-rendering-modes-guide",[592],{"type":33,"value":593},"Nuxt 渲染模式选择指南：SSR/SSG/SPA 应该怎么选",{"type":27,"tag":51,"props":595,"children":596},{},[597],{"type":27,"tag":588,"props":598,"children":600},{"href":599},"/topics/nuxt/nuxt-devtools-guide",[601],{"type":33,"value":602},"Nuxt DevTools 完全指南：提升 10 倍开发效率的调试神器",{"type":27,"tag":51,"props":604,"children":605},{},[606],{"type":27,"tag":588,"props":607,"children":609},{"href":608},"/topics/design/design-system-complete-guide",[610],{"type":33,"value":611},"设计系统建立完整指南：从原则到组件落地",{"type":27,"tag":51,"props":613,"children":614},{},[615],{"type":27,"tag":588,"props":616,"children":618},{"href":617},"/topics/frontend/component-library-architecture-guide",[619],{"type":33,"value":620},"组件库架构设计实践：构建可扩展的企业级 UI 组件库",{"title":7,"searchDepth":622,"depth":622,"links":623},3,[624,626,627,628,629,630,631,632,633,638],{"id":30,"depth":625,"text":34},2,{"id":74,"depth":625,"text":77},{"id":211,"depth":625,"text":214},{"id":255,"depth":625,"text":258},{"id":308,"depth":625,"text":311},{"id":365,"depth":625,"text":368},{"id":399,"depth":625,"text":402},{"id":451,"depth":625,"text":454},{"id":538,"depth":625,"text":541,"children":634},[635,636,637],{"id":545,"depth":622,"text":548},{"id":556,"depth":622,"text":559},{"id":567,"depth":622,"text":570},{"id":578,"depth":625,"text":578},"markdown","content:topics:nuxt:nuxt-ui-component-library-guide.md","content","topics/nuxt/nuxt-ui-component-library-guide.md","topics/nuxt/nuxt-ui-component-library-guide","md",[646,1630,2401],{"_path":647,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":648,"description":649,"date":650,"topic":5,"author":11,"tags":651,"image":657,"featured":468,"readingTime":658,"body":659,"_type":639,"_id":1627,"_source":641,"_file":1628,"_stem":1629,"_extension":644},"/topics/nuxt/nitro-engine-deep-dive","Nitro 引擎深度剖析","讲透 Nuxt/Nitro 的运行时模型、路由与中间件、存储层与缓存、部署适配与性能调优，帮助你把服务端能力当成可控的工程系统。","2026-01-20",[15,652,653,654,655,656],"Nitro","SSR","Serverless","Edge","缓存","/images/topics/nuxt/nitro.jpg",21,{"type":24,"children":660,"toc":1595},[661,666,678,683,741,746,751,755,761,766,789,794,812,815,821,826,849,854,857,879,890,908,919,932,938,961,964,970,975,1006,1011,1024,1027,1033,1045,1058,1063,1081,1086,1099,1102,1108,1113,1131,1137,1156,1162,1167,1172,1201,1204,1210,1215,1233,1238,1256,1262,1275,1281,1294,1300,1313,1318,1331,1334,1340,1346,1359,1365,1378,1384,1397,1400,1406,1411,1434,1439,1452,1455,1461,1466,1524,1529,1547,1550,1555,1567,1572],{"type":27,"tag":28,"props":662,"children":664},{"id":663},"nitro-引擎深度剖析",[665],{"type":33,"value":648},{"type":27,"tag":36,"props":667,"children":668},{},[669,671,676],{"type":33,"value":670},"在 Nuxt 3/4 的体系里，Nitro 不是“一个服务器”，而是一套",{"type":27,"tag":67,"props":672,"children":673},{},[674],{"type":33,"value":675},"可移植的服务端运行时与构建产物规范",{"type":33,"value":677},"。",{"type":27,"tag":36,"props":679,"children":680},{},[681],{"type":33,"value":682},"它把你在开发时写的：",{"type":27,"tag":47,"props":684,"children":685},{},[686,697,708,719,730],{"type":27,"tag":51,"props":687,"children":688},{},[689,695],{"type":27,"tag":297,"props":690,"children":692},{"className":691},[],[693],{"type":33,"value":694},"server/api/*",{"type":33,"value":696},"（API 路由）",{"type":27,"tag":51,"props":698,"children":699},{},[700,706],{"type":27,"tag":297,"props":701,"children":703},{"className":702},[],[704],{"type":33,"value":705},"server/routes/*",{"type":33,"value":707},"（更底层路由）",{"type":27,"tag":51,"props":709,"children":710},{},[711,717],{"type":27,"tag":297,"props":712,"children":714},{"className":713},[],[715],{"type":33,"value":716},"server/middleware/*",{"type":33,"value":718},"（中间件）",{"type":27,"tag":51,"props":720,"children":721},{},[722,728],{"type":27,"tag":297,"props":723,"children":725},{"className":724},[],[726],{"type":33,"value":727},"server/plugins/*",{"type":33,"value":729},"（启动插件）",{"type":27,"tag":51,"props":731,"children":732},{},[733,739],{"type":27,"tag":297,"props":734,"children":736},{"className":735},[],[737],{"type":33,"value":738},"storage",{"type":33,"value":740},"（KV/文件/内存等存储抽象）",{"type":27,"tag":36,"props":742,"children":743},{},[744],{"type":33,"value":745},"统一编译成一个可以部署到多种环境的产物：Node Server、Serverless、Edge（取决于适配器与能力集）。",{"type":27,"tag":36,"props":747,"children":748},{},[749],{"type":33,"value":750},"这篇文章按“你要在生产上稳定运行”的视角，拆解 Nitro 的关键构件，并给出性能与可观测性落地建议。",{"type":27,"tag":752,"props":753,"children":754},"hr",{},[],{"type":27,"tag":28,"props":756,"children":758},{"id":757},"_1-nitro-的定位从-nuxt-ssr-到通用服务端运行时",[759],{"type":33,"value":760},"1. Nitro 的定位：从 Nuxt SSR 到“通用服务端运行时”",{"type":27,"tag":36,"props":762,"children":763},{},[764],{"type":33,"value":765},"Nitro 解决两类问题：",{"type":27,"tag":265,"props":767,"children":768},{},[769,779],{"type":27,"tag":51,"props":770,"children":771},{},[772,777],{"type":27,"tag":67,"props":773,"children":774},{},[775],{"type":33,"value":776},"运行时统一",{"type":33,"value":778},"：开发/生产环境一致的请求处理模型",{"type":27,"tag":51,"props":780,"children":781},{},[782,787],{"type":27,"tag":67,"props":783,"children":784},{},[785],{"type":33,"value":786},"部署可移植",{"type":33,"value":788},"：同一套代码可输出到不同部署目标",{"type":27,"tag":36,"props":790,"children":791},{},[792],{"type":33,"value":793},"你可以把 Nitro 看作 Nuxt 的“服务端内核”，而 Nuxt 只是围绕它提供：",{"type":27,"tag":47,"props":795,"children":796},{},[797,802,807],{"type":27,"tag":51,"props":798,"children":799},{},[800],{"type":33,"value":801},"视图渲染（SSR/RSC 相关能力）",{"type":27,"tag":51,"props":803,"children":804},{},[805],{"type":33,"value":806},"资源构建（Vite/Webpack）",{"type":27,"tag":51,"props":808,"children":809},{},[810],{"type":33,"value":811},"路由与数据获取的上层抽象",{"type":27,"tag":752,"props":813,"children":814},{},[],{"type":27,"tag":28,"props":816,"children":818},{"id":817},"_2-请求生命周期一次请求在-nitro-里怎么走",[819],{"type":33,"value":820},"2. 请求生命周期：一次请求在 Nitro 里怎么走？",{"type":27,"tag":36,"props":822,"children":823},{},[824],{"type":33,"value":825},"简化后的请求链路：",{"type":27,"tag":265,"props":827,"children":828},{},[829,834,839,844],{"type":27,"tag":51,"props":830,"children":831},{},[832],{"type":33,"value":833},"入口适配器接收请求（Node/Serverless/Edge）",{"type":27,"tag":51,"props":835,"children":836},{},[837],{"type":33,"value":838},"进入 Nitro 的 H3 请求处理器（统一事件模型）",{"type":27,"tag":51,"props":840,"children":841},{},[842],{"type":33,"value":843},"依次执行：中间件 → 路由匹配 → handler",{"type":27,"tag":51,"props":845,"children":846},{},[847],{"type":33,"value":848},"写回响应（含 headers、缓存策略、流式输出等）",{"type":27,"tag":36,"props":850,"children":851},{},[852],{"type":33,"value":853},"关键点：Nitro 用统一的事件对象承载请求上下文，这让你在不同部署目标下写出的 server 代码保持一致。",{"type":27,"tag":752,"props":855,"children":856},{},[],{"type":27,"tag":28,"props":858,"children":860},{"id":859},"_3-路由系统serverapi-与-serverroutes-的区别",[861,863,869,871,877],{"type":33,"value":862},"3. 路由系统：",{"type":27,"tag":297,"props":864,"children":866},{"className":865},[],[867],{"type":33,"value":868},"server/api",{"type":33,"value":870}," 与 ",{"type":27,"tag":297,"props":872,"children":874},{"className":873},[],[875],{"type":33,"value":876},"server/routes",{"type":33,"value":878}," 的区别",{"type":27,"tag":543,"props":880,"children":882},{"id":881},"_31-serverapi",[883,885],{"type":33,"value":884},"3.1 ",{"type":27,"tag":297,"props":886,"children":888},{"className":887},[],[889],{"type":33,"value":694},{"type":27,"tag":47,"props":891,"children":892},{},[893,898,903],{"type":27,"tag":51,"props":894,"children":895},{},[896],{"type":33,"value":897},"面向 API 的约定式目录",{"type":27,"tag":51,"props":899,"children":900},{},[901],{"type":33,"value":902},"通常返回 JSON",{"type":27,"tag":51,"props":904,"children":905},{},[906],{"type":33,"value":907},"与 Nuxt 的开发体验高度整合",{"type":27,"tag":543,"props":909,"children":911},{"id":910},"_32-serverroutes",[912,914],{"type":33,"value":913},"3.2 ",{"type":27,"tag":297,"props":915,"children":917},{"className":916},[],[918],{"type":33,"value":705},{"type":27,"tag":47,"props":920,"children":921},{},[922,927],{"type":27,"tag":51,"props":923,"children":924},{},[925],{"type":33,"value":926},"更底层，更贴近“HTTP 路由”",{"type":27,"tag":51,"props":928,"children":929},{},[930],{"type":33,"value":931},"更适合做：Webhook、回调、代理、特殊 content-type",{"type":27,"tag":543,"props":933,"children":935},{"id":934},"_33-实践建议",[936],{"type":33,"value":937},"3.3 实践建议",{"type":27,"tag":47,"props":939,"children":940},{},[941,951],{"type":27,"tag":51,"props":942,"children":943},{},[944,946],{"type":33,"value":945},"普通业务 API：优先 ",{"type":27,"tag":297,"props":947,"children":949},{"className":948},[],[950],{"type":33,"value":868},{"type":27,"tag":51,"props":952,"children":953},{},[954,956],{"type":33,"value":955},"需要更强控制（stream、代理、非 JSON）：用 ",{"type":27,"tag":297,"props":957,"children":959},{"className":958},[],[960],{"type":33,"value":876},{"type":27,"tag":752,"props":962,"children":963},{},[],{"type":27,"tag":28,"props":965,"children":967},{"id":966},"_4-中间件全局逻辑的正确放置",[968],{"type":33,"value":969},"4. 中间件：全局逻辑的正确放置",{"type":27,"tag":36,"props":971,"children":972},{},[973],{"type":33,"value":974},"Nitro 中的中间件通常用于：",{"type":27,"tag":47,"props":976,"children":977},{},[978,983,996,1001],{"type":27,"tag":51,"props":979,"children":980},{},[981],{"type":33,"value":982},"鉴权/鉴别请求来源",{"type":27,"tag":51,"props":984,"children":985},{},[986,988,994],{"type":33,"value":987},"注入 ",{"type":27,"tag":297,"props":989,"children":991},{"className":990},[],[992],{"type":33,"value":993},"requestId",{"type":33,"value":995},"、trace 信息",{"type":27,"tag":51,"props":997,"children":998},{},[999],{"type":33,"value":1000},"统一错误处理与日志",{"type":27,"tag":51,"props":1002,"children":1003},{},[1004],{"type":33,"value":1005},"基础安全 headers",{"type":27,"tag":36,"props":1007,"children":1008},{},[1009],{"type":33,"value":1010},"一个推荐的中间件职责边界：",{"type":27,"tag":47,"props":1012,"children":1013},{},[1014,1019],{"type":27,"tag":51,"props":1015,"children":1016},{},[1017],{"type":33,"value":1018},"中间件只做“横切关注点”",{"type":27,"tag":51,"props":1020,"children":1021},{},[1022],{"type":33,"value":1023},"不做具体业务（避免耦合与隐式依赖）",{"type":27,"tag":752,"props":1025,"children":1026},{},[],{"type":27,"tag":28,"props":1028,"children":1030},{"id":1029},"_5-storage-抽象让缓存与数据存取可替换",[1031],{"type":33,"value":1032},"5. Storage 抽象：让缓存与数据存取可替换",{"type":27,"tag":36,"props":1034,"children":1035},{},[1036,1038,1043],{"type":33,"value":1037},"Nitro 的一个被低估的能力是 ",{"type":27,"tag":297,"props":1039,"children":1041},{"className":1040},[],[1042],{"type":33,"value":738},{"type":33,"value":1044},"：",{"type":27,"tag":47,"props":1046,"children":1047},{},[1048,1053],{"type":27,"tag":51,"props":1049,"children":1050},{},[1051],{"type":33,"value":1052},"提供 KV 风格 API",{"type":27,"tag":51,"props":1054,"children":1055},{},[1056],{"type":33,"value":1057},"可接入内存、文件、Redis 等（取决于配置与环境）",{"type":27,"tag":36,"props":1059,"children":1060},{},[1061],{"type":33,"value":1062},"你可以用它做：",{"type":27,"tag":47,"props":1064,"children":1065},{},[1066,1071,1076],{"type":27,"tag":51,"props":1067,"children":1068},{},[1069],{"type":33,"value":1070},"缓存（页面片段、API 结果）",{"type":27,"tag":51,"props":1072,"children":1073},{},[1074],{"type":33,"value":1075},"限流计数器",{"type":27,"tag":51,"props":1077,"children":1078},{},[1079],{"type":33,"value":1080},"临时会话信息",{"type":27,"tag":36,"props":1082,"children":1083},{},[1084],{"type":33,"value":1085},"设计原则：",{"type":27,"tag":47,"props":1087,"children":1088},{},[1089,1094],{"type":27,"tag":51,"props":1090,"children":1091},{},[1092],{"type":33,"value":1093},"把 storage 当成“可失效缓存”，不要当主数据库",{"type":27,"tag":51,"props":1095,"children":1096},{},[1097],{"type":33,"value":1098},"明确 TTL 与清理策略",{"type":27,"tag":752,"props":1100,"children":1101},{},[],{"type":27,"tag":28,"props":1103,"children":1105},{"id":1104},"_6-缓存策略把快变成可控的工程能力",[1106],{"type":33,"value":1107},"6. 缓存策略：把“快”变成可控的工程能力",{"type":27,"tag":36,"props":1109,"children":1110},{},[1111],{"type":33,"value":1112},"Nitro 里的缓存往往涉及三层：",{"type":27,"tag":265,"props":1114,"children":1115},{},[1116,1121,1126],{"type":27,"tag":51,"props":1117,"children":1118},{},[1119],{"type":33,"value":1120},"CDN 缓存（边缘）",{"type":27,"tag":51,"props":1122,"children":1123},{},[1124],{"type":33,"value":1125},"Nitro 运行时缓存（storage）",{"type":27,"tag":51,"props":1127,"children":1128},{},[1129],{"type":33,"value":1130},"上游服务缓存（数据库/服务端）",{"type":27,"tag":543,"props":1132,"children":1134},{"id":1133},"_61-api-缓存的推荐做法",[1135],{"type":33,"value":1136},"6.1 API 缓存的推荐做法",{"type":27,"tag":47,"props":1138,"children":1139},{},[1140,1151],{"type":27,"tag":51,"props":1141,"children":1142},{},[1143,1145],{"type":33,"value":1144},"对“读多写少”的接口做 ",{"type":27,"tag":297,"props":1146,"children":1148},{"className":1147},[],[1149],{"type":33,"value":1150},"stale-while-revalidate",{"type":27,"tag":51,"props":1152,"children":1153},{},[1154],{"type":33,"value":1155},"缓存 key 必须包含：用户态/语言/地区/权限等关键维度",{"type":27,"tag":543,"props":1157,"children":1159},{"id":1158},"_62-不要缓存带用户身份的响应除非你非常确定",[1160],{"type":33,"value":1161},"6.2 不要缓存“带用户身份”的响应（除非你非常确定）",{"type":27,"tag":36,"props":1163,"children":1164},{},[1165],{"type":33,"value":1166},"最容易出事故的是把 A 用户的数据缓存给 B 用户。",{"type":27,"tag":36,"props":1168,"children":1169},{},[1170],{"type":33,"value":1171},"建议：",{"type":27,"tag":47,"props":1173,"children":1174},{},[1175,1180],{"type":27,"tag":51,"props":1176,"children":1177},{},[1178],{"type":33,"value":1179},"默认对用户态接口不缓存",{"type":27,"tag":51,"props":1181,"children":1182},{},[1183,1185,1191,1193,1199],{"type":33,"value":1184},"必须缓存时，key 中加入 ",{"type":27,"tag":297,"props":1186,"children":1188},{"className":1187},[],[1189],{"type":33,"value":1190},"userId",{"type":33,"value":1192}," 或 ",{"type":27,"tag":297,"props":1194,"children":1196},{"className":1195},[],[1197],{"type":33,"value":1198},"session",{"type":33,"value":1200}," 维度",{"type":27,"tag":752,"props":1202,"children":1203},{},[],{"type":27,"tag":28,"props":1205,"children":1207},{"id":1206},"_7-部署适配为什么同一套代码能跑在不同环境",[1208],{"type":33,"value":1209},"7. 部署适配：为什么同一套代码能跑在不同环境？",{"type":27,"tag":36,"props":1211,"children":1212},{},[1213],{"type":33,"value":1214},"Nitro 的部署产物通常包含：",{"type":27,"tag":47,"props":1216,"children":1217},{},[1218,1223,1228],{"type":27,"tag":51,"props":1219,"children":1220},{},[1221],{"type":33,"value":1222},"编译后的 server bundle",{"type":27,"tag":51,"props":1224,"children":1225},{},[1226],{"type":33,"value":1227},"路由清单与运行时配置",{"type":27,"tag":51,"props":1229,"children":1230},{},[1231],{"type":33,"value":1232},"静态资源与预渲染结果（如果启用）",{"type":27,"tag":36,"props":1234,"children":1235},{},[1236],{"type":33,"value":1237},"在不同目标下的差异主要在：",{"type":27,"tag":47,"props":1239,"children":1240},{},[1241,1246,1251],{"type":27,"tag":51,"props":1242,"children":1243},{},[1244],{"type":33,"value":1245},"运行时能力（Node API 是否可用）",{"type":27,"tag":51,"props":1247,"children":1248},{},[1249],{"type":33,"value":1250},"冷启动与并发模型",{"type":27,"tag":51,"props":1252,"children":1253},{},[1254],{"type":33,"value":1255},"文件系统是否可写",{"type":27,"tag":543,"props":1257,"children":1259},{"id":1258},"_71-node-server",[1260],{"type":33,"value":1261},"7.1 Node Server",{"type":27,"tag":47,"props":1263,"children":1264},{},[1265,1270],{"type":27,"tag":51,"props":1266,"children":1267},{},[1268],{"type":33,"value":1269},"能力最完整",{"type":27,"tag":51,"props":1271,"children":1272},{},[1273],{"type":33,"value":1274},"适合长连接、websocket（需配合平台）",{"type":27,"tag":543,"props":1276,"children":1278},{"id":1277},"_72-serverless",[1279],{"type":33,"value":1280},"7.2 Serverless",{"type":27,"tag":47,"props":1282,"children":1283},{},[1284,1289],{"type":27,"tag":51,"props":1285,"children":1286},{},[1287],{"type":33,"value":1288},"冷启动成本、执行时长限制",{"type":27,"tag":51,"props":1290,"children":1291},{},[1292],{"type":33,"value":1293},"更适合 API 型工作负载",{"type":27,"tag":543,"props":1295,"children":1297},{"id":1296},"_73-edge",[1298],{"type":33,"value":1299},"7.3 Edge",{"type":27,"tag":47,"props":1301,"children":1302},{},[1303,1308],{"type":27,"tag":51,"props":1304,"children":1305},{},[1306],{"type":33,"value":1307},"延迟更低",{"type":27,"tag":51,"props":1309,"children":1310},{},[1311],{"type":33,"value":1312},"运行时限制更严格（例如 Node API 不可用）",{"type":27,"tag":36,"props":1314,"children":1315},{},[1316],{"type":33,"value":1317},"实践建议：",{"type":27,"tag":47,"props":1319,"children":1320},{},[1321,1326],{"type":27,"tag":51,"props":1322,"children":1323},{},[1324],{"type":33,"value":1325},"如果你依赖复杂 Node 能力（例如图像处理、原生模块），优先 Node/Serverless",{"type":27,"tag":51,"props":1327,"children":1328},{},[1329],{"type":33,"value":1330},"如果你追求极致延迟且逻辑简单，考虑 Edge",{"type":27,"tag":752,"props":1332,"children":1333},{},[],{"type":27,"tag":28,"props":1335,"children":1337},{"id":1336},"_8-性能调优nitro-侧你能做什么",[1338],{"type":33,"value":1339},"8. 性能调优：Nitro 侧你能做什么？",{"type":27,"tag":543,"props":1341,"children":1343},{"id":1342},"_81-减少阻塞-io",[1344],{"type":33,"value":1345},"8.1 减少阻塞 I/O",{"type":27,"tag":47,"props":1347,"children":1348},{},[1349,1354],{"type":27,"tag":51,"props":1350,"children":1351},{},[1352],{"type":33,"value":1353},"避免请求内做同步文件读写",{"type":27,"tag":51,"props":1355,"children":1356},{},[1357],{"type":33,"value":1358},"对“配置/规则”等可缓存数据做启动预热",{"type":27,"tag":543,"props":1360,"children":1362},{"id":1361},"_82-控制上游依赖",[1363],{"type":33,"value":1364},"8.2 控制上游依赖",{"type":27,"tag":47,"props":1366,"children":1367},{},[1368,1373],{"type":27,"tag":51,"props":1369,"children":1370},{},[1371],{"type":33,"value":1372},"给外部请求设超时（例如 2~3s）",{"type":27,"tag":51,"props":1374,"children":1375},{},[1376],{"type":33,"value":1377},"加重试要谨慎（避免雪崩）",{"type":27,"tag":543,"props":1379,"children":1381},{"id":1380},"_83-响应体积与压缩",[1382],{"type":33,"value":1383},"8.3 响应体积与压缩",{"type":27,"tag":47,"props":1385,"children":1386},{},[1387,1392],{"type":27,"tag":51,"props":1388,"children":1389},{},[1390],{"type":33,"value":1391},"JSON 输出控制字段",{"type":27,"tag":51,"props":1393,"children":1394},{},[1395],{"type":33,"value":1396},"开启 gzip/br",{"type":27,"tag":752,"props":1398,"children":1399},{},[],{"type":27,"tag":28,"props":1401,"children":1403},{"id":1402},"_9-可观测性没有观测就没有稳定",[1404],{"type":33,"value":1405},"9. 可观测性：没有观测就没有“稳定”",{"type":27,"tag":36,"props":1407,"children":1408},{},[1409],{"type":33,"value":1410},"建议 Nitro 侧最小可观测集合：",{"type":27,"tag":47,"props":1412,"children":1413},{},[1414,1419,1424,1429],{"type":27,"tag":51,"props":1415,"children":1416},{},[1417],{"type":33,"value":1418},"requestId/traceId",{"type":27,"tag":51,"props":1420,"children":1421},{},[1422],{"type":33,"value":1423},"关键路由耗时（p50/p95）",{"type":27,"tag":51,"props":1425,"children":1426},{},[1427],{"type":33,"value":1428},"错误率（按路由/按状态码）",{"type":27,"tag":51,"props":1430,"children":1431},{},[1432],{"type":33,"value":1433},"上游依赖耗时（DB/HTTP）",{"type":27,"tag":36,"props":1435,"children":1436},{},[1437],{"type":33,"value":1438},"落地方式：",{"type":27,"tag":47,"props":1440,"children":1441},{},[1442,1447],{"type":27,"tag":51,"props":1443,"children":1444},{},[1445],{"type":33,"value":1446},"在中间件注入 requestId",{"type":27,"tag":51,"props":1448,"children":1449},{},[1450],{"type":33,"value":1451},"在统一错误处理处记录结构化日志",{"type":27,"tag":752,"props":1453,"children":1454},{},[],{"type":27,"tag":28,"props":1456,"children":1458},{"id":1457},"_10-一个推荐的-nitro-工程结构",[1459],{"type":33,"value":1460},"10. 一个推荐的 Nitro 工程结构",{"type":27,"tag":36,"props":1462,"children":1463},{},[1464],{"type":33,"value":1465},"在 Nuxt 项目里，你可以这样组织服务端代码：",{"type":27,"tag":47,"props":1467,"children":1468},{},[1469,1480,1491,1502,1513],{"type":27,"tag":51,"props":1470,"children":1471},{},[1472,1478],{"type":27,"tag":297,"props":1473,"children":1475},{"className":1474},[],[1476],{"type":33,"value":1477},"server/middleware/",{"type":33,"value":1479},"：鉴权、日志、headers、rate limit",{"type":27,"tag":51,"props":1481,"children":1482},{},[1483,1489],{"type":27,"tag":297,"props":1484,"children":1486},{"className":1485},[],[1487],{"type":33,"value":1488},"server/api/",{"type":33,"value":1490},"：业务 API（薄控制器）",{"type":27,"tag":51,"props":1492,"children":1493},{},[1494,1500],{"type":27,"tag":297,"props":1495,"children":1497},{"className":1496},[],[1498],{"type":33,"value":1499},"server/services/",{"type":33,"value":1501},"：领域服务（可复用）",{"type":27,"tag":51,"props":1503,"children":1504},{},[1505,1511],{"type":27,"tag":297,"props":1506,"children":1508},{"className":1507},[],[1509],{"type":33,"value":1510},"server/repositories/",{"type":33,"value":1512},"：数据访问层",{"type":27,"tag":51,"props":1514,"children":1515},{},[1516,1522],{"type":27,"tag":297,"props":1517,"children":1519},{"className":1518},[],[1520],{"type":33,"value":1521},"server/utils/",{"type":33,"value":1523},"：纯工具",{"type":27,"tag":36,"props":1525,"children":1526},{},[1527],{"type":33,"value":1528},"目标是：",{"type":27,"tag":47,"props":1530,"children":1531},{},[1532,1537,1542],{"type":27,"tag":51,"props":1533,"children":1534},{},[1535],{"type":33,"value":1536},"handler 只做协议适配",{"type":27,"tag":51,"props":1538,"children":1539},{},[1540],{"type":33,"value":1541},"业务逻辑可复用、可测试",{"type":27,"tag":51,"props":1543,"children":1544},{},[1545],{"type":33,"value":1546},"横切能力集中化",{"type":27,"tag":752,"props":1548,"children":1549},{},[],{"type":27,"tag":28,"props":1551,"children":1553},{"id":1552},"总结",[1554],{"type":33,"value":1552},{"type":27,"tag":36,"props":1556,"children":1557},{},[1558,1560,1565],{"type":33,"value":1559},"Nitro 的本质是：把 Nuxt 的服务端能力变成一个",{"type":27,"tag":67,"props":1561,"children":1562},{},[1563],{"type":33,"value":1564},"可编译、可移植、可观测",{"type":33,"value":1566},"的运行时系统。",{"type":27,"tag":36,"props":1568,"children":1569},{},[1570],{"type":33,"value":1571},"你一旦理解了它的生命周期与边界，就可以更有信心地在 Nuxt 里做：",{"type":27,"tag":47,"props":1573,"children":1574},{},[1575,1580,1585,1590],{"type":27,"tag":51,"props":1576,"children":1577},{},[1578],{"type":33,"value":1579},"性能友好的 API",{"type":27,"tag":51,"props":1581,"children":1582},{},[1583],{"type":33,"value":1584},"可控的缓存",{"type":27,"tag":51,"props":1586,"children":1587},{},[1588],{"type":33,"value":1589},"稳定的鉴权与错误处理",{"type":27,"tag":51,"props":1591,"children":1592},{},[1593],{"type":33,"value":1594},"面向多环境部署的工程架构",{"title":7,"searchDepth":622,"depth":622,"links":1596},[1597,1598,1599,1600,1608,1609,1610,1614,1619,1624,1625,1626],{"id":663,"depth":625,"text":648},{"id":757,"depth":625,"text":760},{"id":817,"depth":625,"text":820},{"id":859,"depth":625,"text":1601,"children":1602},"3. 路由系统：server/api 与 server/routes 的区别",[1603,1605,1607],{"id":881,"depth":622,"text":1604},"3.1 server/api/*",{"id":910,"depth":622,"text":1606},"3.2 server/routes/*",{"id":934,"depth":622,"text":937},{"id":966,"depth":625,"text":969},{"id":1029,"depth":625,"text":1032},{"id":1104,"depth":625,"text":1107,"children":1611},[1612,1613],{"id":1133,"depth":622,"text":1136},{"id":1158,"depth":622,"text":1161},{"id":1206,"depth":625,"text":1209,"children":1615},[1616,1617,1618],{"id":1258,"depth":622,"text":1261},{"id":1277,"depth":622,"text":1280},{"id":1296,"depth":622,"text":1299},{"id":1336,"depth":625,"text":1339,"children":1620},[1621,1622,1623],{"id":1342,"depth":622,"text":1345},{"id":1361,"depth":622,"text":1364},{"id":1380,"depth":622,"text":1383},{"id":1402,"depth":625,"text":1405},{"id":1457,"depth":625,"text":1460},{"id":1552,"depth":625,"text":1552},"content:topics:nuxt:nitro-engine-deep-dive.md","topics/nuxt/nitro-engine-deep-dive.md","topics/nuxt/nitro-engine-deep-dive",{"_path":590,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":1631,"description":1632,"date":650,"topic":5,"author":11,"tags":1633,"image":1637,"featured":468,"readingTime":1638,"body":1639,"_type":639,"_id":2398,"_source":641,"_file":2399,"_stem":2400,"_extension":644},"Nuxt 渲染模式选择指南","从 SEO、性能、成本与一致性出发，系统对比 Nuxt 的 CSR/SSR/SSG/ISR（与预渲染）等模式，给出可执行的选型矩阵与落地架构建议。",[15,653,1634,1635,1636],"SSG","ISR","SEO","/images/topics/nuxt/rendering-modes.jpg",22,{"type":24,"children":1640,"toc":2381},[1641,1646,1651,1656,1684,1696,1699,1705,1710,1733,1738,1741,1747,1753,1758,1776,1781,1800,1806,1810,1823,1827,1840,1846,1850,1863,1867,1880,1886,1891,1904,1908,1921,1925,1938,1944,1948,1961,1965,1978,1981,1987,1992,2151,2154,2160,2165,2183,2188,2201,2204,2210,2215,2220,2243,2248,2266,2269,2275,2293,2296,2302,2351,2354,2358,2363],{"type":27,"tag":28,"props":1642,"children":1644},{"id":1643},"nuxt-渲染模式选择指南",[1645],{"type":33,"value":1631},{"type":27,"tag":36,"props":1647,"children":1648},{},[1649],{"type":33,"value":1650},"“到底要不要 SSR？”是 Nuxt 项目里最常见、也最容易吵起来的问题。",{"type":27,"tag":36,"props":1652,"children":1653},{},[1654],{"type":33,"value":1655},"原因是：渲染模式不是一个单点选择，它同时牵动：",{"type":27,"tag":47,"props":1657,"children":1658},{},[1659,1664,1669,1674,1679],{"type":27,"tag":51,"props":1660,"children":1661},{},[1662],{"type":33,"value":1663},"SEO（可索引内容是否直出）",{"type":27,"tag":51,"props":1665,"children":1666},{},[1667],{"type":33,"value":1668},"性能（TTFB/LCP/INP）",{"type":27,"tag":51,"props":1670,"children":1671},{},[1672],{"type":33,"value":1673},"成本（回源、算力、带宽）",{"type":27,"tag":51,"props":1675,"children":1676},{},[1677],{"type":33,"value":1678},"一致性（内容更新策略、缓存失效）",{"type":27,"tag":51,"props":1680,"children":1681},{},[1682],{"type":33,"value":1683},"工程复杂度（部署、观测、回滚）",{"type":27,"tag":36,"props":1685,"children":1686},{},[1687,1689,1694],{"type":33,"value":1688},"这篇文章给你一套",{"type":27,"tag":67,"props":1690,"children":1691},{},[1692],{"type":33,"value":1693},"可执行的选型方法",{"type":33,"value":1695},"：先定义目标，再选模式，最后给落地结构与检查清单。",{"type":27,"tag":752,"props":1697,"children":1698},{},[],{"type":27,"tag":28,"props":1700,"children":1702},{"id":1701},"_1-四个维度决定你的模式",[1703],{"type":33,"value":1704},"1. 四个维度，决定你的模式",{"type":27,"tag":36,"props":1706,"children":1707},{},[1708],{"type":33,"value":1709},"在做任何选择前，先回答四个问题：",{"type":27,"tag":265,"props":1711,"children":1712},{},[1713,1718,1723,1728],{"type":27,"tag":51,"props":1714,"children":1715},{},[1716],{"type":33,"value":1717},"页面是否需要 SEO？（搜索引擎是否必须看到正文）",{"type":27,"tag":51,"props":1719,"children":1720},{},[1721],{"type":33,"value":1722},"数据是否强一致？（用户态/支付/权限）",{"type":27,"tag":51,"props":1724,"children":1725},{},[1726],{"type":33,"value":1727},"更新频率如何？（发布频繁 vs 偶尔）",{"type":27,"tag":51,"props":1729,"children":1730},{},[1731],{"type":33,"value":1732},"流量模型是什么？（突发、平稳、长尾）",{"type":27,"tag":36,"props":1734,"children":1735},{},[1736],{"type":33,"value":1737},"这些问题比“SSR 快还是慢”更重要。",{"type":27,"tag":752,"props":1739,"children":1740},{},[],{"type":27,"tag":28,"props":1742,"children":1744},{"id":1743},"_2-主要模式概览csr-ssr-ssg-isr-预渲染",[1745],{"type":33,"value":1746},"2. 主要模式概览：CSR / SSR / SSG / ISR / 预渲染",{"type":27,"tag":543,"props":1748,"children":1750},{"id":1749},"_21-csr纯客户端渲染",[1751],{"type":33,"value":1752},"2.1 CSR（纯客户端渲染）",{"type":27,"tag":36,"props":1754,"children":1755},{},[1756],{"type":33,"value":1757},"特点：",{"type":27,"tag":47,"props":1759,"children":1760},{},[1761,1766,1771],{"type":27,"tag":51,"props":1762,"children":1763},{},[1764],{"type":33,"value":1765},"HTML 只有壳",{"type":27,"tag":51,"props":1767,"children":1768},{},[1769],{"type":33,"value":1770},"SEO 风险大（除非你不索引）",{"type":27,"tag":51,"props":1772,"children":1773},{},[1774],{"type":33,"value":1775},"首屏性能取决于 JS 与接口",{"type":27,"tag":36,"props":1777,"children":1778},{},[1779],{"type":33,"value":1780},"适用：",{"type":27,"tag":47,"props":1782,"children":1783},{},[1784,1789],{"type":27,"tag":51,"props":1785,"children":1786},{},[1787],{"type":33,"value":1788},"用户中心、后台、强交互工具",{"type":27,"tag":51,"props":1790,"children":1791},{},[1792,1794],{"type":33,"value":1793},"不需要索引或明确 ",{"type":27,"tag":297,"props":1795,"children":1797},{"className":1796},[],[1798],{"type":33,"value":1799},"noindex",{"type":27,"tag":543,"props":1801,"children":1803},{"id":1802},"_22-ssr服务端渲染",[1804],{"type":33,"value":1805},"2.2 SSR（服务端渲染）",{"type":27,"tag":36,"props":1807,"children":1808},{},[1809],{"type":33,"value":1757},{"type":27,"tag":47,"props":1811,"children":1812},{},[1813,1818],{"type":27,"tag":51,"props":1814,"children":1815},{},[1816],{"type":33,"value":1817},"首屏 HTML 直出，SEO 友好",{"type":27,"tag":51,"props":1819,"children":1820},{},[1821],{"type":33,"value":1822},"每次请求可能都需要回源（需要缓存）",{"type":27,"tag":36,"props":1824,"children":1825},{},[1826],{"type":33,"value":1780},{"type":27,"tag":47,"props":1828,"children":1829},{},[1830,1835],{"type":27,"tag":51,"props":1831,"children":1832},{},[1833],{"type":33,"value":1834},"内容需要 SEO，但数据强动态",{"type":27,"tag":51,"props":1836,"children":1837},{},[1838],{"type":33,"value":1839},"你有完善的缓存策略",{"type":27,"tag":543,"props":1841,"children":1843},{"id":1842},"_23-ssg静态生成",[1844],{"type":33,"value":1845},"2.3 SSG（静态生成）",{"type":27,"tag":36,"props":1847,"children":1848},{},[1849],{"type":33,"value":1757},{"type":27,"tag":47,"props":1851,"children":1852},{},[1853,1858],{"type":27,"tag":51,"props":1854,"children":1855},{},[1856],{"type":33,"value":1857},"性能与稳定性最好",{"type":27,"tag":51,"props":1859,"children":1860},{},[1861],{"type":33,"value":1862},"更新成本在“构建时”",{"type":27,"tag":36,"props":1864,"children":1865},{},[1866],{"type":33,"value":1780},{"type":27,"tag":47,"props":1868,"children":1869},{},[1870,1875],{"type":27,"tag":51,"props":1871,"children":1872},{},[1873],{"type":33,"value":1874},"内容站、文档站、营销页",{"type":27,"tag":51,"props":1876,"children":1877},{},[1878],{"type":33,"value":1879},"更新频率不高或可接受构建延迟",{"type":27,"tag":543,"props":1881,"children":1883},{"id":1882},"_24-isr增量静态再生按需生成",[1884],{"type":33,"value":1885},"2.4 ISR（增量静态再生/按需生成）",{"type":27,"tag":36,"props":1887,"children":1888},{},[1889],{"type":33,"value":1890},"在 Nuxt 体系里，ISR 的表达可能来自：",{"type":27,"tag":47,"props":1892,"children":1893},{},[1894,1899],{"type":27,"tag":51,"props":1895,"children":1896},{},[1897],{"type":33,"value":1898},"生成策略 + 缓存策略",{"type":27,"tag":51,"props":1900,"children":1901},{},[1902],{"type":33,"value":1903},"或配合边缘缓存与按需失效",{"type":27,"tag":36,"props":1905,"children":1906},{},[1907],{"type":33,"value":1757},{"type":27,"tag":47,"props":1909,"children":1910},{},[1911,1916],{"type":27,"tag":51,"props":1912,"children":1913},{},[1914],{"type":33,"value":1915},"静态化收益 + 可控更新",{"type":27,"tag":51,"props":1917,"children":1918},{},[1919],{"type":33,"value":1920},"需要你设计“失效与再生成”",{"type":27,"tag":36,"props":1922,"children":1923},{},[1924],{"type":33,"value":1780},{"type":27,"tag":47,"props":1926,"children":1927},{},[1928,1933],{"type":27,"tag":51,"props":1929,"children":1930},{},[1931],{"type":33,"value":1932},"内容更新频繁，但仍要 SEO",{"type":27,"tag":51,"props":1934,"children":1935},{},[1936],{"type":33,"value":1937},"你希望在高峰也保持稳定",{"type":27,"tag":543,"props":1939,"children":1941},{"id":1940},"_25-预渲染prerender",[1942],{"type":33,"value":1943},"2.5 预渲染（prerender）",{"type":27,"tag":36,"props":1945,"children":1946},{},[1947],{"type":33,"value":1757},{"type":27,"tag":47,"props":1949,"children":1950},{},[1951,1956],{"type":27,"tag":51,"props":1952,"children":1953},{},[1954],{"type":33,"value":1955},"对部分路由预先生成 HTML",{"type":27,"tag":51,"props":1957,"children":1958},{},[1959],{"type":33,"value":1960},"适合混合站点",{"type":27,"tag":36,"props":1962,"children":1963},{},[1964],{"type":33,"value":1780},{"type":27,"tag":47,"props":1966,"children":1967},{},[1968,1973],{"type":27,"tag":51,"props":1969,"children":1970},{},[1971],{"type":33,"value":1972},"首页/核心落地页需要 SEO",{"type":27,"tag":51,"props":1974,"children":1975},{},[1976],{"type":33,"value":1977},"工具页/用户页不需要 SEO",{"type":27,"tag":752,"props":1979,"children":1980},{},[],{"type":27,"tag":28,"props":1982,"children":1984},{"id":1983},"_3-选型矩阵可直接用",[1985],{"type":33,"value":1986},"3. 选型矩阵（可直接用）",{"type":27,"tag":36,"props":1988,"children":1989},{},[1990],{"type":33,"value":1991},"你可以按路由维度做选型，而不是全站一刀切。",{"type":27,"tag":84,"props":1993,"children":1994},{},[1995,2020],{"type":27,"tag":88,"props":1996,"children":1997},{},[1998],{"type":27,"tag":92,"props":1999,"children":2000},{},[2001,2006,2010,2015],{"type":27,"tag":96,"props":2002,"children":2003},{},[2004],{"type":33,"value":2005},"页面类型",{"type":27,"tag":96,"props":2007,"children":2008},{},[2009],{"type":33,"value":1636},{"type":27,"tag":96,"props":2011,"children":2012},{},[2013],{"type":33,"value":2014},"更新频率",{"type":27,"tag":96,"props":2016,"children":2017},{},[2018],{"type":33,"value":2019},"推荐",{"type":27,"tag":112,"props":2021,"children":2022},{},[2023,2044,2065,2086,2107,2129],{"type":27,"tag":92,"props":2024,"children":2025},{},[2026,2031,2035,2039],{"type":27,"tag":119,"props":2027,"children":2028},{},[2029],{"type":33,"value":2030},"文章详情",{"type":27,"tag":119,"props":2032,"children":2033},{},[2034],{"type":33,"value":128},{"type":27,"tag":119,"props":2036,"children":2037},{},[2038],{"type":33,"value":180},{"type":27,"tag":119,"props":2040,"children":2041},{},[2042],{"type":33,"value":2043},"SSG/ISR",{"type":27,"tag":92,"props":2045,"children":2046},{},[2047,2052,2056,2060],{"type":27,"tag":119,"props":2048,"children":2049},{},[2050],{"type":33,"value":2051},"文章列表",{"type":27,"tag":119,"props":2053,"children":2054},{},[2055],{"type":33,"value":128},{"type":27,"tag":119,"props":2057,"children":2058},{},[2059],{"type":33,"value":180},{"type":27,"tag":119,"props":2061,"children":2062},{},[2063],{"type":33,"value":2064},"SSG/ISR（注意聚合页）",{"type":27,"tag":92,"props":2066,"children":2067},{},[2068,2073,2077,2081],{"type":27,"tag":119,"props":2069,"children":2070},{},[2071],{"type":33,"value":2072},"产品详情",{"type":27,"tag":119,"props":2074,"children":2075},{},[2076],{"type":33,"value":128},{"type":27,"tag":119,"props":2078,"children":2079},{},[2080],{"type":33,"value":128},{"type":27,"tag":119,"props":2082,"children":2083},{},[2084],{"type":33,"value":2085},"ISR/SSR（配缓存）",{"type":27,"tag":92,"props":2087,"children":2088},{},[2089,2094,2098,2102],{"type":27,"tag":119,"props":2090,"children":2091},{},[2092],{"type":33,"value":2093},"搜索结果",{"type":27,"tag":119,"props":2095,"children":2096},{},[2097],{"type":33,"value":180},{"type":27,"tag":119,"props":2099,"children":2100},{},[2101],{"type":33,"value":128},{"type":27,"tag":119,"props":2103,"children":2104},{},[2105],{"type":33,"value":2106},"SSR/CSR（配 noindex）",{"type":27,"tag":92,"props":2108,"children":2109},{},[2110,2115,2120,2124],{"type":27,"tag":119,"props":2111,"children":2112},{},[2113],{"type":33,"value":2114},"用户中心",{"type":27,"tag":119,"props":2116,"children":2117},{},[2118],{"type":33,"value":2119},"低",{"type":27,"tag":119,"props":2121,"children":2122},{},[2123],{"type":33,"value":128},{"type":27,"tag":119,"props":2125,"children":2126},{},[2127],{"type":33,"value":2128},"CSR",{"type":27,"tag":92,"props":2130,"children":2131},{},[2132,2137,2142,2146],{"type":27,"tag":119,"props":2133,"children":2134},{},[2135],{"type":33,"value":2136},"工具页",{"type":27,"tag":119,"props":2138,"children":2139},{},[2140],{"type":33,"value":2141},"低/中",{"type":27,"tag":119,"props":2143,"children":2144},{},[2145],{"type":33,"value":180},{"type":27,"tag":119,"props":2147,"children":2148},{},[2149],{"type":33,"value":2150},"CSR + 预渲染核心路由",{"type":27,"tag":752,"props":2152,"children":2153},{},[],{"type":27,"tag":28,"props":2155,"children":2157},{"id":2156},"_4-混合渲染真正的生产最优解",[2158],{"type":33,"value":2159},"4. 混合渲染：真正的生产最优解",{"type":27,"tag":36,"props":2161,"children":2162},{},[2163],{"type":33,"value":2164},"生产上最常见的模式是混合：",{"type":27,"tag":47,"props":2166,"children":2167},{},[2168,2173,2178],{"type":27,"tag":51,"props":2169,"children":2170},{},[2171],{"type":33,"value":2172},"公共内容：静态化（SSG/ISR）+ CDN",{"type":27,"tag":51,"props":2174,"children":2175},{},[2176],{"type":33,"value":2177},"用户态内容：CSR 或 SSR（private/no-store）",{"type":27,"tag":51,"props":2179,"children":2180},{},[2181],{"type":33,"value":2182},"关键落地页：预渲染",{"type":27,"tag":36,"props":2184,"children":2185},{},[2186],{"type":33,"value":2187},"好处：",{"type":27,"tag":47,"props":2189,"children":2190},{},[2191,2196],{"type":27,"tag":51,"props":2192,"children":2193},{},[2194],{"type":33,"value":2195},"SEO 与性能兼得",{"type":27,"tag":51,"props":2197,"children":2198},{},[2199],{"type":33,"value":2200},"成本可控",{"type":27,"tag":752,"props":2202,"children":2203},{},[],{"type":27,"tag":28,"props":2205,"children":2207},{"id":2206},"_5-缓存与失效模式落地的关键",[2208],{"type":33,"value":2209},"5. 缓存与失效：模式落地的关键",{"type":27,"tag":36,"props":2211,"children":2212},{},[2213],{"type":33,"value":2214},"无论你选 SSR 还是 ISR，本质都离不开缓存。",{"type":27,"tag":36,"props":2216,"children":2217},{},[2218],{"type":33,"value":2219},"建议把缓存分层：",{"type":27,"tag":47,"props":2221,"children":2222},{},[2223,2228,2233,2238],{"type":27,"tag":51,"props":2224,"children":2225},{},[2226],{"type":33,"value":2227},"浏览器",{"type":27,"tag":51,"props":2229,"children":2230},{},[2231],{"type":33,"value":2232},"CDN",{"type":27,"tag":51,"props":2234,"children":2235},{},[2236],{"type":33,"value":2237},"应用侧（server runtime）",{"type":27,"tag":51,"props":2239,"children":2240},{},[2241],{"type":33,"value":2242},"数据侧（Redis/DB）",{"type":27,"tag":36,"props":2244,"children":2245},{},[2246],{"type":33,"value":2247},"并给每条路由明确：",{"type":27,"tag":47,"props":2249,"children":2250},{},[2251,2256,2261],{"type":27,"tag":51,"props":2252,"children":2253},{},[2254],{"type":33,"value":2255},"是否 public/private",{"type":27,"tag":51,"props":2257,"children":2258},{},[2259],{"type":33,"value":2260},"TTL 多久",{"type":27,"tag":51,"props":2262,"children":2263},{},[2264],{"type":33,"value":2265},"写操作后如何失效",{"type":27,"tag":752,"props":2267,"children":2268},{},[],{"type":27,"tag":28,"props":2270,"children":2272},{"id":2271},"_6-常见误区",[2273],{"type":33,"value":2274},"6. 常见误区",{"type":27,"tag":47,"props":2276,"children":2277},{},[2278,2283,2288],{"type":27,"tag":51,"props":2279,"children":2280},{},[2281],{"type":33,"value":2282},"“SSR 一定更快”：不一定，TTFB 可能更慢；LCP 受资源与主线程影响更大",{"type":27,"tag":51,"props":2284,"children":2285},{},[2286],{"type":33,"value":2287},"“SSG 一定更好”：构建成本与发布延迟可能无法接受",{"type":27,"tag":51,"props":2289,"children":2290},{},[2291],{"type":33,"value":2292},"“全站一个模式最省事”：短期省事，长期很难优化与扩展",{"type":27,"tag":752,"props":2294,"children":2295},{},[],{"type":27,"tag":28,"props":2297,"children":2299},{"id":2298},"_7-上线检查清单",[2300],{"type":33,"value":2301},"7. 上线检查清单",{"type":27,"tag":47,"props":2303,"children":2305},{"className":2304},[458],[2306,2315,2324,2333,2342],{"type":27,"tag":51,"props":2307,"children":2309},{"className":2308},[463],[2310,2313],{"type":27,"tag":466,"props":2311,"children":2312},{"disabled":468,"type":469},[],{"type":33,"value":2314}," 按路由明确 SEO 需求（哪些可索引）",{"type":27,"tag":51,"props":2316,"children":2318},{"className":2317},[463],[2319,2322],{"type":27,"tag":466,"props":2320,"children":2321},{"disabled":468,"type":469},[],{"type":33,"value":2323}," 用户态页面是否 private/no-store",{"type":27,"tag":51,"props":2325,"children":2327},{"className":2326},[463],[2328,2331],{"type":27,"tag":466,"props":2329,"children":2330},{"disabled":468,"type":469},[],{"type":33,"value":2332}," 公共内容是否走 CDN 并有合理 TTL",{"type":27,"tag":51,"props":2334,"children":2336},{"className":2335},[463],[2337,2340],{"type":27,"tag":466,"props":2338,"children":2339},{"disabled":468,"type":469},[],{"type":33,"value":2341}," 更新路径是否有失效机制（发布事件）",{"type":27,"tag":51,"props":2343,"children":2345},{"className":2344},[463],[2346,2349],{"type":27,"tag":466,"props":2347,"children":2348},{"disabled":468,"type":469},[],{"type":33,"value":2350}," 是否有 RUM/日志来验证效果",{"type":27,"tag":752,"props":2352,"children":2353},{},[],{"type":27,"tag":28,"props":2355,"children":2356},{"id":1552},[2357],{"type":33,"value":1552},{"type":27,"tag":36,"props":2359,"children":2360},{},[2361],{"type":33,"value":2362},"Nuxt 渲染模式选型的正确做法是：",{"type":27,"tag":47,"props":2364,"children":2365},{},[2366,2371,2376],{"type":27,"tag":51,"props":2367,"children":2368},{},[2369],{"type":33,"value":2370},"以“页面类型”而不是“站点整体”做选择",{"type":27,"tag":51,"props":2372,"children":2373},{},[2374],{"type":33,"value":2375},"把缓存与失效当成一等公民",{"type":27,"tag":51,"props":2377,"children":2378},{},[2379],{"type":33,"value":2380},"用观测验证，而不是凭感觉",{"title":7,"searchDepth":622,"depth":622,"links":2382},[2383,2384,2385,2392,2393,2394,2395,2396,2397],{"id":1643,"depth":625,"text":1631},{"id":1701,"depth":625,"text":1704},{"id":1743,"depth":625,"text":1746,"children":2386},[2387,2388,2389,2390,2391],{"id":1749,"depth":622,"text":1752},{"id":1802,"depth":622,"text":1805},{"id":1842,"depth":622,"text":1845},{"id":1882,"depth":622,"text":1885},{"id":1940,"depth":622,"text":1943},{"id":1983,"depth":625,"text":1986},{"id":2156,"depth":625,"text":2159},{"id":2206,"depth":625,"text":2209},{"id":2271,"depth":625,"text":2274},{"id":2298,"depth":625,"text":2301},{"id":1552,"depth":625,"text":1552},"content:topics:nuxt:nuxt-rendering-modes-guide.md","topics/nuxt/nuxt-rendering-modes-guide.md","topics/nuxt/nuxt-rendering-modes-guide",{"_path":2402,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":2403,"description":2404,"date":2405,"topic":5,"author":11,"tags":2406,"image":2411,"featured":468,"readingTime":2412,"body":2413,"_type":639,"_id":2938,"_source":641,"_file":2939,"_stem":2940,"_extension":644},"/topics/nuxt/nuxt4-major-updates-overview","Nuxt 4 重大更新全面解读：架构升级与开发体验革新","深入解析 Nuxt 4 的重大更新，包括新目录结构、Nitro 2.0 引擎、兼容性层变化、性能优化等核心改进，帮助开发者全面了解新版本特性并做好升级准备。","2026-01-18",[2407,2408,653,2409,2410],"Nuxt 4","Vue","全栈框架","版本升级","/images/topics/nuxt/nuxt4-features-overview.jpg",16,{"type":24,"children":2414,"toc":2899},[2415,2421,2427,2432,2437,2443,2449,2454,2462,2470,2478,2484,2489,2500,2506,2515,2521,2527,2532,2541,2547,2556,2562,2571,2577,2583,2592,2598,2607,2613,2622,2628,2634,2643,2649,2658,2664,2675,2684,2690,2696,2705,2711,2720,2726,2735,2741,2747,2756,2762,2771,2777,2783,2793,2799,2808,2814,2819,2824,2829,2847,2850,2855],{"type":27,"tag":28,"props":2416,"children":2418},{"id":2417},"nuxt-4-重大更新全面解读",[2419],{"type":33,"value":2420},"Nuxt 4 重大更新全面解读",{"type":27,"tag":28,"props":2422,"children":2424},{"id":2423},"引言nuxt-的又一次进化",[2425],{"type":33,"value":2426},"引言：Nuxt 的又一次进化",{"type":27,"tag":36,"props":2428,"children":2429},{},[2430],{"type":33,"value":2431},"Nuxt 4 的发布标志着这个 Vue 生态中最受欢迎的全栈框架又迈入了新阶段。从 Nuxt 2 到 Nuxt 3 是一次彻底重写，而 Nuxt 3 到 Nuxt 4 则是在成熟架构上的精进打磨——更清晰的目录结构、更强大的引擎、更好的开发体验。",{"type":27,"tag":36,"props":2433,"children":2434},{},[2435],{"type":33,"value":2436},"这篇文章将全面解读 Nuxt 4 的核心变化，帮助你理解这些改动背后的设计理念，以及它们将如何影响你的日常开发。",{"type":27,"tag":28,"props":2438,"children":2440},{"id":2439},"第一部分新目录结构",[2441],{"type":33,"value":2442},"第一部分：新目录结构",{"type":27,"tag":543,"props":2444,"children":2446},{"id":2445},"_11-从扁平到分层",[2447],{"type":33,"value":2448},"1.1 从扁平到分层",{"type":27,"tag":36,"props":2450,"children":2451},{},[2452],{"type":33,"value":2453},"Nuxt 4 引入了新的目录结构，将应用代码与配置分离：",{"type":27,"tag":289,"props":2455,"children":2457},{"code":2456},"# Nuxt 3 目录结构\nproject/\n├── .nuxt/\n├── app.vue\n├── components/\n├── composables/\n├── layouts/\n├── middleware/\n├── pages/\n├── plugins/\n├── public/\n├── server/\n├── nuxt.config.ts\n└── package.json\n\n# Nuxt 4 新目录结构\nproject/\n├── .nuxt/\n├── app/                  # 应用代码集中在 app/ 目录\n│   ├── app.vue\n│   ├── components/\n│   ├── composables/\n│   ├── layouts/\n│   ├── middleware/\n│   ├── pages/\n│   └── plugins/\n├── public/\n├── server/\n├── nuxt.config.ts\n└── package.json\n",[2458],{"type":27,"tag":297,"props":2459,"children":2460},{"__ignoreMap":7},[2461],{"type":33,"value":2456},{"type":27,"tag":36,"props":2463,"children":2464},{},[2465],{"type":27,"tag":67,"props":2466,"children":2467},{},[2468],{"type":33,"value":2469},"为什么这样设计？",{"type":27,"tag":289,"props":2471,"children":2473},{"code":2472},"┌────────────────────────────────────────────────────────────┐\n│              新目录结构的设计理念                            │\n├────────────────────────────────────────────────────────────┤\n│                                                            │\n│  1. 关注点分离                                             │\n│     ├── app/ - 客户端/同构代码                             │\n│     ├── server/ - 服务端代码                               │\n│     └── 根目录 - 配置和公共资源                             │\n│                                                            │\n│  2. 更清晰的项目边界                                       │\n│     ├── Monorepo 友好                                      │\n│     ├── 多应用项目更清晰                                   │\n│     └── 与其他框架惯例对齐                                 │\n│                                                            │\n│  3. 未来扩展性                                             │\n│     ├── 为多前端支持做准备                                 │\n│     └── 便于工具链识别和处理                               │\n│                                                            │\n└────────────────────────────────────────────────────────────┘\n",[2474],{"type":27,"tag":297,"props":2475,"children":2476},{"__ignoreMap":7},[2477],{"type":33,"value":2472},{"type":27,"tag":543,"props":2479,"children":2481},{"id":2480},"_12-向后兼容",[2482],{"type":33,"value":2483},"1.2 向后兼容",{"type":27,"tag":36,"props":2485,"children":2486},{},[2487],{"type":33,"value":2488},"Nuxt 4 提供了兼容性选项，允许继续使用旧目录结构：",{"type":27,"tag":289,"props":2490,"children":2495},{"code":2491,"language":2492,"meta":7,"className":2493},"// nuxt.config.ts\nexport default defineNuxtConfig({\n  future: {\n    compatibilityVersion: 4  // 启用 Nuxt 4 特性\n  },\n  \n  // 如果需要继续使用旧目录结构\n  srcDir: './',  // 而不是 'app/'\n  \n  // 或者自定义目录\n  dir: {\n    app: 'src',\n    pages: 'src/pages',\n    layouts: 'src/layouts'\n  }\n});\n","typescript",[2494],"language-typescript",[2496],{"type":27,"tag":297,"props":2497,"children":2498},{"__ignoreMap":7},[2499],{"type":33,"value":2491},{"type":27,"tag":543,"props":2501,"children":2503},{"id":2502},"_13-appconfigts-变化",[2504],{"type":33,"value":2505},"1.3 app.config.ts 变化",{"type":27,"tag":289,"props":2507,"children":2510},{"code":2508,"language":2492,"meta":7,"className":2509},"// Nuxt 3: app.config.ts 在项目根目录\n// Nuxt 4: app.config.ts 移入 app/ 目录\n\n// app/app.config.ts\nexport default defineAppConfig({\n  ui: {\n    primary: 'green',\n    gray: 'slate'\n  },\n  \n  // 类型安全的应用配置\n  meta: {\n    name: 'My App',\n    description: 'A Nuxt 4 Application'\n  }\n});\n\n// 使用方式不变\nconst appConfig = useAppConfig();\nconsole.log(appConfig.ui.primary);  // 'green'\n",[2494],[2511],{"type":27,"tag":297,"props":2512,"children":2513},{"__ignoreMap":7},[2514],{"type":33,"value":2508},{"type":27,"tag":28,"props":2516,"children":2518},{"id":2517},"第二部分nitro-20-引擎升级",[2519],{"type":33,"value":2520},"第二部分：Nitro 2.0 引擎升级",{"type":27,"tag":543,"props":2522,"children":2524},{"id":2523},"_21-性能提升",[2525],{"type":33,"value":2526},"2.1 性能提升",{"type":27,"tag":36,"props":2528,"children":2529},{},[2530],{"type":33,"value":2531},"Nitro 2.0 带来了显著的性能改进：",{"type":27,"tag":289,"props":2533,"children":2536},{"code":2534,"language":2492,"meta":7,"className":2535},"// 冷启动时间优化\n// Nitro 1.x: ~150ms\n// Nitro 2.0: ~80ms (约 47% 提升)\n\n// 内存占用优化\n// 同样的应用，内存占用减少约 20%\n\n// 原因：\n// - 更高效的模块加载\n// - 优化的树摇（tree-shaking）\n// - 减少运行时开销\n",[2494],[2537],{"type":27,"tag":297,"props":2538,"children":2539},{"__ignoreMap":7},[2540],{"type":33,"value":2534},{"type":27,"tag":543,"props":2542,"children":2544},{"id":2543},"_22-新的路由系统",[2545],{"type":33,"value":2546},"2.2 新的路由系统",{"type":27,"tag":289,"props":2548,"children":2551},{"code":2549,"language":2492,"meta":7,"className":2550},"// server/routes/api/[...slug].ts\n\n// Nitro 2.0 新的路由定义方式\nexport default defineEventHandler({\n  // 路由级别配置\n  config: {\n    // 缓存配置\n    cache: {\n      maxAge: 60,\n      staleMaxAge: 3600,\n      swr: true\n    },\n    \n    // CORS 配置\n    cors: {\n      origin: ['https://example.com'],\n      methods: ['GET', 'POST']\n    }\n  },\n  \n  // 处理函数\n  handler: async (event) => {\n    const slug = event.context.params?.slug;\n    return { data: await fetchData(slug) };\n  }\n});\n\n// 支持中间件链\nexport default defineEventHandler({\n  onRequest: [authMiddleware, rateLimitMiddleware],\n  onBeforeResponse: [logMiddleware],\n  \n  handler: (event) => {\n    return { message: 'Hello' };\n  }\n});\n",[2494],[2552],{"type":27,"tag":297,"props":2553,"children":2554},{"__ignoreMap":7},[2555],{"type":33,"value":2549},{"type":27,"tag":543,"props":2557,"children":2559},{"id":2558},"_23-增强的数据获取",[2560],{"type":33,"value":2561},"2.3 增强的数据获取",{"type":27,"tag":289,"props":2563,"children":2566},{"code":2564,"language":2492,"meta":7,"className":2565},"// Nitro 2.0 改进的 $fetch\n\n// 自动请求去重\nconst [user, posts] = await Promise.all([\n  $fetch('/api/user/1'),\n  $fetch('/api/user/1')  // 相同请求自动去重\n]);\n\n// 请求拦截器\nexport default defineNuxtPlugin(() => {\n  const { $fetch } = useNuxtApp();\n  \n  // 全局请求配置\n  globalThis.$fetch = $fetch.create({\n    onRequest({ request, options }) {\n      options.headers = {\n        ...options.headers,\n        Authorization: `Bearer ${getToken()}`\n      };\n    },\n    \n    onResponseError({ response }) {\n      if (response.status === 401) {\n        navigateTo('/login');\n      }\n    }\n  });\n});\n",[2494],[2567],{"type":27,"tag":297,"props":2568,"children":2569},{"__ignoreMap":7},[2570],{"type":33,"value":2564},{"type":27,"tag":28,"props":2572,"children":2574},{"id":2573},"第三部分兼容性层变化",[2575],{"type":33,"value":2576},"第三部分：兼容性层变化",{"type":27,"tag":543,"props":2578,"children":2580},{"id":2579},"_31-移除的废弃-api",[2581],{"type":33,"value":2582},"3.1 移除的废弃 API",{"type":27,"tag":289,"props":2584,"children":2587},{"code":2585,"language":2492,"meta":7,"className":2586},"// Nuxt 4 移除了 Nuxt 3 中标记为废弃的 API\n\n// ❌ 已移除\nimport { defineNuxtRouteMiddleware } from '#app'\n\n// ✅ 使用新的 API\nimport { defineNuxtRouteMiddleware } from 'nuxt/app'\n\n// ❌ 已移除\nconst nuxtApp = useNuxtApp()\nnuxtApp.$router  // 不再有 $ 前缀\n\n// ✅ 使用 composables\nconst router = useRouter()\n\n// ❌ 已移除\nuseAsyncData('key', () => fetch(), { lazy: true })\n\n// ✅ 使用 useLazyAsyncData\nuseLazyAsyncData('key', () => fetch())\n",[2494],[2588],{"type":27,"tag":297,"props":2589,"children":2590},{"__ignoreMap":7},[2591],{"type":33,"value":2585},{"type":27,"tag":543,"props":2593,"children":2595},{"id":2594},"_32-类型系统改进",[2596],{"type":33,"value":2597},"3.2 类型系统改进",{"type":27,"tag":289,"props":2599,"children":2602},{"code":2600,"language":2492,"meta":7,"className":2601},"// Nuxt 4 增强的类型推导\n\n// 页面元数据类型\n// pages/dashboard.vue\n\u003Cscript setup lang=\"ts\">\ndefinePageMeta({\n  // 类型自动推导，IDE 自动补全\n  layout: 'admin',  // 只能填已定义的布局\n  middleware: ['auth'],  // 只能填已定义的中间件\n  \n  // 自定义元数据\n  title: '仪表盘',\n  requiresAuth: true\n});\n\u003C/script>\n\n// 路由参数类型\n// pages/users/[id].vue\n\u003Cscript setup lang=\"ts\">\nconst route = useRoute('users-id');\n//             ^? RouteLocationNormalized\u003C'users-id'>\n\nroute.params.id  // 类型: string\n\u003C/script>\n\n// 运行时配置类型\n// nuxt.config.ts\nexport default defineNuxtConfig({\n  runtimeConfig: {\n    // 私有配置（仅服务端）\n    apiSecret: '',\n    \n    // 公开配置\n    public: {\n      apiBase: ''\n    }\n  }\n});\n\n// 使用时自动推导类型\nconst config = useRuntimeConfig();\nconfig.apiSecret;  // 服务端可用\nconfig.public.apiBase;  // 客户端可用\n",[2494],[2603],{"type":27,"tag":297,"props":2604,"children":2605},{"__ignoreMap":7},[2606],{"type":33,"value":2600},{"type":27,"tag":543,"props":2608,"children":2610},{"id":2609},"_33-useasyncdata-改进",[2611],{"type":33,"value":2612},"3.3 useAsyncData 改进",{"type":27,"tag":289,"props":2614,"children":2617},{"code":2615,"language":2492,"meta":7,"className":2616},"// Nuxt 4 中 useAsyncData 的改进\n\n// 改进 1：更好的错误处理\nconst { data, error, status } = await useAsyncData('users', () => $fetch('/api/users'));\n\n// status 新增更多状态\n// 'idle' | 'pending' | 'success' | 'error'\n\n// 改进 2：简化的刷新机制\nconst { refresh, clear } = await useAsyncData('users', () => $fetch('/api/users'));\n\n// 带参数刷新\nawait refresh({ dedupe: true });\n\n// 清除缓存\nclear();\n\n// 改进 3：深度响应式默认关闭\nconst { data } = await useAsyncData('config', () => $fetch('/api/config'), {\n  deep: false  // 默认 false，提升性能\n});\n\n// 需要深度响应式时显式开启\nconst { data } = await useAsyncData('form', () => $fetch('/api/form'), {\n  deep: true\n});\n",[2494],[2618],{"type":27,"tag":297,"props":2619,"children":2620},{"__ignoreMap":7},[2621],{"type":33,"value":2615},{"type":27,"tag":28,"props":2623,"children":2625},{"id":2624},"第四部分开发体验改进",[2626],{"type":33,"value":2627},"第四部分：开发体验改进",{"type":27,"tag":543,"props":2629,"children":2631},{"id":2630},"_41-nuxt-devtools-增强",[2632],{"type":33,"value":2633},"4.1 Nuxt DevTools 增强",{"type":27,"tag":289,"props":2635,"children":2638},{"code":2636,"language":2492,"meta":7,"className":2637},"// Nuxt 4 内置增强版 DevTools\n\n// 新功能：\n// 1. 组件性能分析\n// - 渲染时间追踪\n// - 不必要渲染检测\n// - 内存使用监控\n\n// 2. 数据流可视化\n// - useAsyncData 调用时序图\n// - 数据缓存状态\n// - 请求去重可视化\n\n// 3. 路由调试\n// - 路由匹配过程\n// - 中间件执行顺序\n// - 导航守卫状态\n\n// 启用高级功能\nexport default defineNuxtConfig({\n  devtools: {\n    enabled: true,\n    \n    // 新选项\n    timeline: {\n      enabled: true  // 启用时间线\n    }\n  }\n});\n",[2494],[2639],{"type":27,"tag":297,"props":2640,"children":2641},{"__ignoreMap":7},[2642],{"type":33,"value":2636},{"type":27,"tag":543,"props":2644,"children":2646},{"id":2645},"_42-热更新优化",[2647],{"type":33,"value":2648},"4.2 热更新优化",{"type":27,"tag":289,"props":2650,"children":2653},{"code":2651,"language":2492,"meta":7,"className":2652},"// Nuxt 4 大幅改进了热更新体验\n\n// 1. 更快的 HMR\n// - 组件变更：\u003C 100ms\n// - 页面变更：\u003C 200ms\n// - 配置变更：\u003C 1s\n\n// 2. 保持状态的更新\n// composables 更新不再丢失组件状态\nconst count = ref(0);  // 更新文件后，值保持\n\n// 3. 错误恢复\n// 修复语法错误后自动恢复，无需重启\n",[2494],[2654],{"type":27,"tag":297,"props":2655,"children":2656},{"__ignoreMap":7},[2657],{"type":33,"value":2651},{"type":27,"tag":543,"props":2659,"children":2661},{"id":2660},"_43-错误处理增强",[2662],{"type":33,"value":2663},"4.3 错误处理增强",{"type":27,"tag":289,"props":2665,"children":2670},{"code":2666,"language":2667,"meta":7,"className":2668},"\u003C!-- app/error.vue - 增强的错误页面 -->\n\u003Ctemplate>\n  \u003Cdiv class=\"error-page\">\n    \u003Ch1>{{ error.statusCode }}\u003C/h1>\n    \u003Cp>{{ error.message }}\u003C/p>\n    \n    \u003C!-- Nuxt 4 新增：错误堆栈（开发环境） -->\n    \u003Cpre v-if=\"isDev && error.stack\">{{ error.stack }}\u003C/pre>\n    \n    \u003C!-- 新增：错误上下文 -->\n    \u003Cdetails v-if=\"error.data\">\n      \u003Csummary>详细信息\u003C/summary>\n      \u003Cpre>{{ error.data }}\u003C/pre>\n    \u003C/details>\n    \n    \u003Cbutton @click=\"handleError\">重试\u003C/button>\n  \u003C/div>\n\u003C/template>\n\n\u003Cscript setup lang=\"ts\">\nconst props = defineProps\u003C{\n  error: {\n    statusCode: number\n    message: string\n    stack?: string\n    data?: Record\u003Cstring, unknown>\n  }\n}>();\n\nconst isDev = process.dev;\n\nfunction handleError() {\n  clearError({ redirect: '/' });\n}\n\u003C/script>\n","vue",[2669],"language-vue",[2671],{"type":27,"tag":297,"props":2672,"children":2673},{"__ignoreMap":7},[2674],{"type":33,"value":2666},{"type":27,"tag":289,"props":2676,"children":2679},{"code":2677,"language":2492,"meta":7,"className":2678},"// server/api/users.ts - 增强的服务端错误\n\nexport default defineEventHandler((event) => {\n  const id = getRouterParam(event, 'id');\n  \n  if (!id) {\n    throw createError({\n      statusCode: 400,\n      message: '缺少用户 ID',\n      \n      // Nuxt 4 新增：结构化错误数据\n      data: {\n        field: 'id',\n        constraint: 'required'\n      }\n    });\n  }\n  \n  // 业务错误\n  throw createError({\n    statusCode: 404,\n    message: '用户不存在',\n    data: {\n      userId: id,\n      suggestion: '请检查用户 ID 是否正确'\n    }\n  });\n});\n",[2494],[2680],{"type":27,"tag":297,"props":2681,"children":2682},{"__ignoreMap":7},[2683],{"type":33,"value":2677},{"type":27,"tag":28,"props":2685,"children":2687},{"id":2686},"第五部分性能优化特性",[2688],{"type":33,"value":2689},"第五部分：性能优化特性",{"type":27,"tag":543,"props":2691,"children":2693},{"id":2692},"_51-更智能的代码分割",[2694],{"type":33,"value":2695},"5.1 更智能的代码分割",{"type":27,"tag":289,"props":2697,"children":2700},{"code":2698,"language":2492,"meta":7,"className":2699},"// Nuxt 4 的自动代码分割更加智能\n\n// 自动路由分割\n// pages/dashboard/\n//   index.vue      -> chunks/dashboard.js\n//   settings.vue   -> chunks/dashboard-settings.js\n//   analytics.vue  -> chunks/dashboard-analytics.js\n\n// 组件级分割\n// components/\n//   HeavyChart.vue -> chunks/heavy-chart.js (自动延迟加载)\n\n// 手动优化\nexport default defineNuxtConfig({\n  vite: {\n    build: {\n      rollupOptions: {\n        output: {\n          // 自定义分块策略\n          manualChunks: {\n            'vendor-vue': ['vue', 'vue-router', 'pinia'],\n            'vendor-ui': ['element-plus']\n          }\n        }\n      }\n    }\n  }\n});\n",[2494],[2701],{"type":27,"tag":297,"props":2702,"children":2703},{"__ignoreMap":7},[2704],{"type":33,"value":2698},{"type":27,"tag":543,"props":2706,"children":2708},{"id":2707},"_52-图片优化增强",[2709],{"type":33,"value":2710},"5.2 图片优化增强",{"type":27,"tag":289,"props":2712,"children":2715},{"code":2713,"language":2667,"meta":7,"className":2714},"\u003C!-- Nuxt 4 的 nuxt-img 增强 -->\n\u003Ctemplate>\n  \u003CNuxtImg\n    src=\"/images/hero.jpg\"\n    \n    \u003C!-- 新增：自动格式选择 -->\n    format=\"webp,avif\"\n    \n    \u003C!-- 新增：艺术指导响应式 -->\n    :sources=\"[\n      { media: '(max-width: 640px)', src: '/images/hero-mobile.jpg' },\n      { media: '(max-width: 1024px)', src: '/images/hero-tablet.jpg' }\n    ]\"\n    \n    \u003C!-- 新增：模糊占位符 -->\n    placeholder=\"/images/hero-blur.jpg\"\n    \n    \u003C!-- 新增：性能提示 -->\n    :priority=\"true\"\n    fetchpriority=\"high\"\n  />\n\u003C/template>\n\n\u003Cscript setup>\n// 编程式使用\nconst img = useImage();\n\n// 生成优化后的 URL\nconst optimizedUrl = img('/images/photo.jpg', {\n  width: 800,\n  height: 600,\n  format: 'webp',\n  quality: 80\n});\n\u003C/script>\n",[2669],[2716],{"type":27,"tag":297,"props":2717,"children":2718},{"__ignoreMap":7},[2719],{"type":33,"value":2713},{"type":27,"tag":543,"props":2721,"children":2723},{"id":2722},"_53-服务端渲染优化",[2724],{"type":33,"value":2725},"5.3 服务端渲染优化",{"type":27,"tag":289,"props":2727,"children":2730},{"code":2728,"language":2492,"meta":7,"className":2729},"// Nuxt 4 SSR 性能优化\n\n// 1. 流式 SSR\n// nuxt.config.ts\nexport default defineNuxtConfig({\n  nitro: {\n    // 启用流式 SSR\n    experimental: {\n      wasm: true\n    }\n  },\n  \n  // 组件流式渲染\n  experimental: {\n    componentIslands: true,  // 组件岛\n    payloadExtraction: true  // Payload 提取\n  }\n});\n\n// 2. 选择性 Hydration\n// pages/article/[id].vue\n\u003Ctemplate>\n  \u003Carticle>\n    \u003C!-- 静态内容，不需要 hydration -->\n    \u003CNuxtIsland name=\"ArticleContent\" :props=\"{ content }\" />\n    \n    \u003C!-- 需要交互的部分 -->\n    \u003CCommentSection :articleId=\"id\" />\n  \u003C/article>\n\u003C/template>\n\n// 3. 预加载优化\n\u003Cscript setup>\n// 智能预加载\nconst { data } = await useAsyncData('article', () => $fetch('/api/article/' + id), {\n  // 预加载相关数据\n  preload: [\n    () => $fetch('/api/comments/' + id),\n    () => $fetch('/api/related/' + id)\n  ]\n});\n\u003C/script>\n",[2494],[2731],{"type":27,"tag":297,"props":2732,"children":2733},{"__ignoreMap":7},[2734],{"type":33,"value":2728},{"type":27,"tag":28,"props":2736,"children":2738},{"id":2737},"第六部分模块生态更新",[2739],{"type":33,"value":2740},"第六部分：模块生态更新",{"type":27,"tag":543,"props":2742,"children":2744},{"id":2743},"_61-官方模块适配",[2745],{"type":33,"value":2746},"6.1 官方模块适配",{"type":27,"tag":289,"props":2748,"children":2751},{"code":2749,"language":2492,"meta":7,"className":2750},"// 主要官方模块的 Nuxt 4 兼容版本\n\n// @nuxtjs/i18n v9\nexport default defineNuxtConfig({\n  modules: ['@nuxtjs/i18n'],\n  \n  i18n: {\n    // 新增：编译时优化\n    bundle: {\n      optimizeTranslations: true\n    },\n    \n    // 新增：类型生成\n    types: 'composition'\n  }\n});\n\n// @nuxt/content v3\nexport default defineNuxtConfig({\n  modules: ['@nuxt/content'],\n  \n  content: {\n    // 新增：更强的查询 API\n    experimental: {\n      clientDB: true,\n      stripQueryParameters: true\n    }\n  }\n});\n\n// @pinia/nuxt v0.6\nexport default defineNuxtConfig({\n  modules: ['@pinia/nuxt'],\n  \n  pinia: {\n    // 新增：自动导入优化\n    storesDirs: ['./stores/**']\n  }\n});\n",[2494],[2752],{"type":27,"tag":297,"props":2753,"children":2754},{"__ignoreMap":7},[2755],{"type":33,"value":2749},{"type":27,"tag":543,"props":2757,"children":2759},{"id":2758},"_62-创建-nuxt-4-兼容模块",[2760],{"type":33,"value":2761},"6.2 创建 Nuxt 4 兼容模块",{"type":27,"tag":289,"props":2763,"children":2766},{"code":2764,"language":2492,"meta":7,"className":2765},"// 模块开发的新约定\n\n// my-module/src/module.ts\nimport { defineNuxtModule, createResolver } from '@nuxt/kit'\n\nexport default defineNuxtModule({\n  meta: {\n    name: 'my-module',\n    configKey: 'myModule',\n    \n    // Nuxt 4 要求\n    compatibility: {\n      nuxt: '^4.0.0'\n    }\n  },\n  \n  defaults: {\n    enabled: true\n  },\n  \n  setup(options, nuxt) {\n    const resolver = createResolver(import.meta.url);\n    \n    // 使用新的 hook API\n    nuxt.hook('app:resolve', (app) => {\n      // app 配置\n    });\n    \n    // 添加运行时插件\n    addPlugin(resolver.resolve('./runtime/plugin'));\n    \n    // 添加组件\n    addComponentsDir({\n      path: resolver.resolve('./runtime/components'),\n      prefix: 'MyModule'\n    });\n  }\n});\n",[2494],[2767],{"type":27,"tag":297,"props":2768,"children":2769},{"__ignoreMap":7},[2770],{"type":33,"value":2764},{"type":27,"tag":28,"props":2772,"children":2774},{"id":2773},"第七部分迁移准备",[2775],{"type":33,"value":2776},"第七部分：迁移准备",{"type":27,"tag":543,"props":2778,"children":2780},{"id":2779},"_71-兼容性检查清单",[2781],{"type":33,"value":2782},"7.1 兼容性检查清单",{"type":27,"tag":289,"props":2784,"children":2788},{"code":2785,"language":639,"meta":7,"className":2786},"## Nuxt 4 迁移检查清单\n\n### 依赖版本\n- [ ] Node.js >= 20\n- [ ] Vue >= 3.4\n- [ ] TypeScript >= 5.3（推荐）\n\n### 代码检查\n- [ ] 移除已废弃的 API 调用\n- [ ] 更新 composables 导入路径\n- [ ] 检查 useAsyncData 用法\n- [ ] 审查中间件语法\n\n### 目录结构\n- [ ] 决定是否采用新目录结构\n- [ ] 移动文件到 app/ 目录（如果采用）\n- [ ] 更新 nuxt.config.ts 配置\n\n### 模块更新\n- [ ] 更新官方模块到兼容版本\n- [ ] 检查第三方模块兼容性\n- [ ] 更新自定义模块\n\n### 测试\n- [ ] 运行全部测试套件\n- [ ] 验证 SSR/SSG 输出\n- [ ] 检查 hydration 错误\n- [ ] 性能基准测试\n",[2787],"language-markdown",[2789],{"type":27,"tag":297,"props":2790,"children":2791},{"__ignoreMap":7},[2792],{"type":33,"value":2785},{"type":27,"tag":543,"props":2794,"children":2796},{"id":2795},"_72-渐进式升级路径",[2797],{"type":33,"value":2798},"7.2 渐进式升级路径",{"type":27,"tag":289,"props":2800,"children":2803},{"code":2801,"language":2492,"meta":7,"className":2802},"// 使用 compatibilityVersion 实现渐进升级\n\n// 阶段 1：启用 Nuxt 4 特性（保持旧目录结构）\nexport default defineNuxtConfig({\n  future: {\n    compatibilityVersion: 4\n  },\n  srcDir: './'  // 保持旧目录结构\n});\n\n// 阶段 2：迁移到新目录结构\n// 1. 创建 app/ 目录\n// 2. 移动文件\n// 3. 更新导入路径\n\n// 阶段 3：完全升级\nexport default defineNuxtConfig({\n  // 移除 future 配置，默认使用 Nuxt 4 行为\n});\n",[2494],[2804],{"type":27,"tag":297,"props":2805,"children":2806},{"__ignoreMap":7},[2807],{"type":33,"value":2801},{"type":27,"tag":28,"props":2809,"children":2811},{"id":2810},"结语稳步前进的进化",[2812],{"type":33,"value":2813},"结语：稳步前进的进化",{"type":27,"tag":36,"props":2815,"children":2816},{},[2817],{"type":33,"value":2818},"Nuxt 4 不是一次颠覆性的重写，而是在 Nuxt 3 坚实基础上的持续改进。新的目录结构带来更好的组织性，Nitro 2.0 带来更好的性能，增强的类型系统带来更好的开发体验。",{"type":27,"tag":36,"props":2820,"children":2821},{},[2822],{"type":33,"value":2823},"对于 Nuxt 3 用户来说，升级路径相对平滑。核心概念没有变化，熟悉的 API 依然工作。Nuxt 团队显然吸取了 Nuxt 2 到 Nuxt 3 升级的经验，这次提供了更友好的迁移体验。",{"type":27,"tag":36,"props":2825,"children":2826},{},[2827],{"type":33,"value":2828},"如果你正在考虑是否升级，建议：",{"type":27,"tag":47,"props":2830,"children":2831},{},[2832,2837,2842],{"type":27,"tag":51,"props":2833,"children":2834},{},[2835],{"type":33,"value":2836},"新项目直接使用 Nuxt 4",{"type":27,"tag":51,"props":2838,"children":2839},{},[2840],{"type":33,"value":2841},"现有项目评估迁移成本后决定",{"type":27,"tag":51,"props":2843,"children":2844},{},[2845],{"type":33,"value":2846},"关注官方迁移指南的更新",{"type":27,"tag":752,"props":2848,"children":2849},{},[],{"type":27,"tag":28,"props":2851,"children":2853},{"id":2852},"参考资源",[2854],{"type":33,"value":2852},{"type":27,"tag":47,"props":2856,"children":2857},{},[2858,2869,2879,2889],{"type":27,"tag":51,"props":2859,"children":2860},{},[2861],{"type":27,"tag":588,"props":2862,"children":2866},{"href":2863,"rel":2864},"https://nuxt.com/blog/v4",[2865],"nofollow",[2867],{"type":33,"value":2868},"Nuxt 4 官方公告",{"type":27,"tag":51,"props":2870,"children":2871},{},[2872],{"type":27,"tag":588,"props":2873,"children":2876},{"href":2874,"rel":2875},"https://nuxt.com/docs/migration/upgrade",[2865],[2877],{"type":33,"value":2878},"Nuxt 4 迁移指南",{"type":27,"tag":51,"props":2880,"children":2881},{},[2882],{"type":27,"tag":588,"props":2883,"children":2886},{"href":2884,"rel":2885},"https://nitro.unjs.io/changelog",[2865],[2887],{"type":33,"value":2888},"Nitro 2.0 更新日志",{"type":27,"tag":51,"props":2890,"children":2891},{},[2892],{"type":27,"tag":588,"props":2893,"children":2896},{"href":2894,"rel":2895},"https://github.com/nuxt/nuxt/issues",[2865],[2897],{"type":33,"value":2898},"Nuxt 路线图",{"title":7,"searchDepth":622,"depth":622,"links":2900},[2901,2902,2903,2908,2913,2918,2923,2928,2932,2936,2937],{"id":2417,"depth":625,"text":2420},{"id":2423,"depth":625,"text":2426},{"id":2439,"depth":625,"text":2442,"children":2904},[2905,2906,2907],{"id":2445,"depth":622,"text":2448},{"id":2480,"depth":622,"text":2483},{"id":2502,"depth":622,"text":2505},{"id":2517,"depth":625,"text":2520,"children":2909},[2910,2911,2912],{"id":2523,"depth":622,"text":2526},{"id":2543,"depth":622,"text":2546},{"id":2558,"depth":622,"text":2561},{"id":2573,"depth":625,"text":2576,"children":2914},[2915,2916,2917],{"id":2579,"depth":622,"text":2582},{"id":2594,"depth":622,"text":2597},{"id":2609,"depth":622,"text":2612},{"id":2624,"depth":625,"text":2627,"children":2919},[2920,2921,2922],{"id":2630,"depth":622,"text":2633},{"id":2645,"depth":622,"text":2648},{"id":2660,"depth":622,"text":2663},{"id":2686,"depth":625,"text":2689,"children":2924},[2925,2926,2927],{"id":2692,"depth":622,"text":2695},{"id":2707,"depth":622,"text":2710},{"id":2722,"depth":622,"text":2725},{"id":2737,"depth":625,"text":2740,"children":2929},[2930,2931],{"id":2743,"depth":622,"text":2746},{"id":2758,"depth":622,"text":2761},{"id":2773,"depth":625,"text":2776,"children":2933},[2934,2935],{"id":2779,"depth":622,"text":2782},{"id":2795,"depth":622,"text":2798},{"id":2810,"depth":625,"text":2813},{"id":2852,"depth":625,"text":2852},"content:topics:nuxt:nuxt4-major-updates-overview.md","topics/nuxt/nuxt4-major-updates-overview.md","topics/nuxt/nuxt4-major-updates-overview",{"_path":4,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":8,"description":9,"date":10,"topic":5,"author":11,"tags":2942,"image":18,"imageQuery":19,"pexelsPhotoId":20,"pexelsUrl":21,"featured":6,"readingTime":22,"body":2943,"_type":639,"_id":640,"_source":641,"_file":642,"_stem":643,"_extension":644},[13,14,15,16,17],{"type":24,"children":2944,"toc":3411},[2945,2949,2953,2957,2968,2976,2980,2984,3083,3087,3091,3095,3099,3118,3122,3126,3130,3145,3149,3157,3161,3165,3169,3173,3188,3192,3207,3211,3215,3230,3234,3238,3242,3257,3261,3276,3280,3348,3352,3356,3360,3364,3368,3372,3376,3380],{"type":27,"tag":28,"props":2946,"children":2947},{"id":30},[2948],{"type":33,"value":34},{"type":27,"tag":36,"props":2950,"children":2951},{},[2952],{"type":33,"value":40},{"type":27,"tag":36,"props":2954,"children":2955},{},[2956],{"type":33,"value":45},{"type":27,"tag":47,"props":2958,"children":2959},{},[2960,2964],{"type":27,"tag":51,"props":2961,"children":2962},{},[2963],{"type":33,"value":55},{"type":27,"tag":51,"props":2965,"children":2966},{},[2967],{"type":33,"value":60},{"type":27,"tag":36,"props":2969,"children":2970},{},[2971,2972],{"type":33,"value":65},{"type":27,"tag":67,"props":2973,"children":2974},{},[2975],{"type":33,"value":71},{"type":27,"tag":28,"props":2977,"children":2978},{"id":74},[2979],{"type":33,"value":77},{"type":27,"tag":36,"props":2981,"children":2982},{},[2983],{"type":33,"value":82},{"type":27,"tag":84,"props":2985,"children":2986},{},[2987,3005],{"type":27,"tag":88,"props":2988,"children":2989},{},[2990],{"type":27,"tag":92,"props":2991,"children":2992},{},[2993,2997,3001],{"type":27,"tag":96,"props":2994,"children":2995},{},[2996],{"type":33,"value":100},{"type":27,"tag":96,"props":2998,"children":2999},{},[3000],{"type":33,"value":105},{"type":27,"tag":96,"props":3002,"children":3003},{},[3004],{"type":33,"value":110},{"type":27,"tag":112,"props":3006,"children":3007},{},[3008,3023,3038,3053,3068],{"type":27,"tag":92,"props":3009,"children":3010},{},[3011,3015,3019],{"type":27,"tag":119,"props":3012,"children":3013},{},[3014],{"type":33,"value":123},{"type":27,"tag":119,"props":3016,"children":3017},{},[3018],{"type":33,"value":128},{"type":27,"tag":119,"props":3020,"children":3021},{},[3022],{"type":33,"value":133},{"type":27,"tag":92,"props":3024,"children":3025},{},[3026,3030,3034],{"type":27,"tag":119,"props":3027,"children":3028},{},[3029],{"type":33,"value":141},{"type":27,"tag":119,"props":3031,"children":3032},{},[3033],{"type":33,"value":128},{"type":27,"tag":119,"props":3035,"children":3036},{},[3037],{"type":33,"value":150},{"type":27,"tag":92,"props":3039,"children":3040},{},[3041,3045,3049],{"type":27,"tag":119,"props":3042,"children":3043},{},[3044],{"type":33,"value":158},{"type":27,"tag":119,"props":3046,"children":3047},{},[3048],{"type":33,"value":128},{"type":27,"tag":119,"props":3050,"children":3051},{},[3052],{"type":33,"value":167},{"type":27,"tag":92,"props":3054,"children":3055},{},[3056,3060,3064],{"type":27,"tag":119,"props":3057,"children":3058},{},[3059],{"type":33,"value":175},{"type":27,"tag":119,"props":3061,"children":3062},{},[3063],{"type":33,"value":180},{"type":27,"tag":119,"props":3065,"children":3066},{},[3067],{"type":33,"value":185},{"type":27,"tag":92,"props":3069,"children":3070},{},[3071,3075,3079],{"type":27,"tag":119,"props":3072,"children":3073},{},[3074],{"type":33,"value":193},{"type":27,"tag":119,"props":3076,"children":3077},{},[3078],{"type":33,"value":198},{"type":27,"tag":119,"props":3080,"children":3081},{},[3082],{"type":33,"value":203},{"type":27,"tag":36,"props":3084,"children":3085},{},[3086],{"type":33,"value":208},{"type":27,"tag":28,"props":3088,"children":3089},{"id":211},[3090],{"type":33,"value":214},{"type":27,"tag":36,"props":3092,"children":3093},{},[3094],{"type":33,"value":219},{"type":27,"tag":36,"props":3096,"children":3097},{},[3098],{"type":33,"value":224},{"type":27,"tag":47,"props":3100,"children":3101},{},[3102,3106,3110,3114],{"type":27,"tag":51,"props":3103,"children":3104},{},[3105],{"type":33,"value":232},{"type":27,"tag":51,"props":3107,"children":3108},{},[3109],{"type":33,"value":237},{"type":27,"tag":51,"props":3111,"children":3112},{},[3113],{"type":33,"value":242},{"type":27,"tag":51,"props":3115,"children":3116},{},[3117],{"type":33,"value":247},{"type":27,"tag":36,"props":3119,"children":3120},{},[3121],{"type":33,"value":252},{"type":27,"tag":28,"props":3123,"children":3124},{"id":255},[3125],{"type":33,"value":258},{"type":27,"tag":36,"props":3127,"children":3128},{},[3129],{"type":33,"value":263},{"type":27,"tag":265,"props":3131,"children":3132},{},[3133,3137,3141],{"type":27,"tag":51,"props":3134,"children":3135},{},[3136],{"type":33,"value":272},{"type":27,"tag":51,"props":3138,"children":3139},{},[3140],{"type":33,"value":277},{"type":27,"tag":51,"props":3142,"children":3143},{},[3144],{"type":33,"value":282},{"type":27,"tag":36,"props":3146,"children":3147},{},[3148],{"type":33,"value":287},{"type":27,"tag":289,"props":3150,"children":3152},{"className":3151,"code":293,"language":294,"meta":7},[292],[3153],{"type":27,"tag":297,"props":3154,"children":3155},{"__ignoreMap":7},[3156],{"type":33,"value":293},{"type":27,"tag":36,"props":3158,"children":3159},{},[3160],{"type":33,"value":305},{"type":27,"tag":28,"props":3162,"children":3163},{"id":308},[3164],{"type":33,"value":311},{"type":27,"tag":36,"props":3166,"children":3167},{},[3168],{"type":33,"value":316},{"type":27,"tag":36,"props":3170,"children":3171},{},[3172],{"type":33,"value":321},{"type":27,"tag":47,"props":3174,"children":3175},{},[3176,3180,3184],{"type":27,"tag":51,"props":3177,"children":3178},{},[3179],{"type":33,"value":329},{"type":27,"tag":51,"props":3181,"children":3182},{},[3183],{"type":33,"value":334},{"type":27,"tag":51,"props":3185,"children":3186},{},[3187],{"type":33,"value":339},{"type":27,"tag":36,"props":3189,"children":3190},{},[3191],{"type":33,"value":344},{"type":27,"tag":47,"props":3193,"children":3194},{},[3195,3199,3203],{"type":27,"tag":51,"props":3196,"children":3197},{},[3198],{"type":33,"value":352},{"type":27,"tag":51,"props":3200,"children":3201},{},[3202],{"type":33,"value":357},{"type":27,"tag":51,"props":3204,"children":3205},{},[3206],{"type":33,"value":362},{"type":27,"tag":28,"props":3208,"children":3209},{"id":365},[3210],{"type":33,"value":368},{"type":27,"tag":36,"props":3212,"children":3213},{},[3214],{"type":33,"value":373},{"type":27,"tag":47,"props":3216,"children":3217},{},[3218,3222,3226],{"type":27,"tag":51,"props":3219,"children":3220},{},[3221],{"type":33,"value":381},{"type":27,"tag":51,"props":3223,"children":3224},{},[3225],{"type":33,"value":386},{"type":27,"tag":51,"props":3227,"children":3228},{},[3229],{"type":33,"value":391},{"type":27,"tag":36,"props":3231,"children":3232},{},[3233],{"type":33,"value":396},{"type":27,"tag":28,"props":3235,"children":3236},{"id":399},[3237],{"type":33,"value":402},{"type":27,"tag":36,"props":3239,"children":3240},{},[3241],{"type":33,"value":407},{"type":27,"tag":47,"props":3243,"children":3244},{},[3245,3249,3253],{"type":27,"tag":51,"props":3246,"children":3247},{},[3248],{"type":33,"value":415},{"type":27,"tag":51,"props":3250,"children":3251},{},[3252],{"type":33,"value":420},{"type":27,"tag":51,"props":3254,"children":3255},{},[3256],{"type":33,"value":425},{"type":27,"tag":36,"props":3258,"children":3259},{},[3260],{"type":33,"value":430},{"type":27,"tag":265,"props":3262,"children":3263},{},[3264,3268,3272],{"type":27,"tag":51,"props":3265,"children":3266},{},[3267],{"type":33,"value":438},{"type":27,"tag":51,"props":3269,"children":3270},{},[3271],{"type":33,"value":443},{"type":27,"tag":51,"props":3273,"children":3274},{},[3275],{"type":33,"value":448},{"type":27,"tag":28,"props":3277,"children":3278},{"id":451},[3279],{"type":33,"value":454},{"type":27,"tag":47,"props":3281,"children":3283},{"className":3282},[458],[3284,3292,3300,3308,3316,3324,3332,3340],{"type":27,"tag":51,"props":3285,"children":3287},{"className":3286},[463],[3288,3291],{"type":27,"tag":466,"props":3289,"children":3290},{"disabled":468,"type":469},[],{"type":33,"value":472},{"type":27,"tag":51,"props":3293,"children":3295},{"className":3294},[463],[3296,3299],{"type":27,"tag":466,"props":3297,"children":3298},{"disabled":468,"type":469},[],{"type":33,"value":481},{"type":27,"tag":51,"props":3301,"children":3303},{"className":3302},[463],[3304,3307],{"type":27,"tag":466,"props":3305,"children":3306},{"disabled":468,"type":469},[],{"type":33,"value":490},{"type":27,"tag":51,"props":3309,"children":3311},{"className":3310},[463],[3312,3315],{"type":27,"tag":466,"props":3313,"children":3314},{"disabled":468,"type":469},[],{"type":33,"value":499},{"type":27,"tag":51,"props":3317,"children":3319},{"className":3318},[463],[3320,3323],{"type":27,"tag":466,"props":3321,"children":3322},{"disabled":468,"type":469},[],{"type":33,"value":508},{"type":27,"tag":51,"props":3325,"children":3327},{"className":3326},[463],[3328,3331],{"type":27,"tag":466,"props":3329,"children":3330},{"disabled":468,"type":469},[],{"type":33,"value":517},{"type":27,"tag":51,"props":3333,"children":3335},{"className":3334},[463],[3336,3339],{"type":27,"tag":466,"props":3337,"children":3338},{"disabled":468,"type":469},[],{"type":33,"value":526},{"type":27,"tag":51,"props":3341,"children":3343},{"className":3342},[463],[3344,3347],{"type":27,"tag":466,"props":3345,"children":3346},{"disabled":468,"type":469},[],{"type":33,"value":535},{"type":27,"tag":28,"props":3349,"children":3350},{"id":538},[3351],{"type":33,"value":541},{"type":27,"tag":543,"props":3353,"children":3354},{"id":545},[3355],{"type":33,"value":548},{"type":27,"tag":36,"props":3357,"children":3358},{},[3359],{"type":33,"value":553},{"type":27,"tag":543,"props":3361,"children":3362},{"id":556},[3363],{"type":33,"value":559},{"type":27,"tag":36,"props":3365,"children":3366},{},[3367],{"type":33,"value":564},{"type":27,"tag":543,"props":3369,"children":3370},{"id":567},[3371],{"type":33,"value":570},{"type":27,"tag":36,"props":3373,"children":3374},{},[3375],{"type":33,"value":575},{"type":27,"tag":28,"props":3377,"children":3378},{"id":578},[3379],{"type":33,"value":578},{"type":27,"tag":47,"props":3381,"children":3382},{},[3383,3390,3397,3404],{"type":27,"tag":51,"props":3384,"children":3385},{},[3386],{"type":27,"tag":588,"props":3387,"children":3388},{"href":590},[3389],{"type":33,"value":593},{"type":27,"tag":51,"props":3391,"children":3392},{},[3393],{"type":27,"tag":588,"props":3394,"children":3395},{"href":599},[3396],{"type":33,"value":602},{"type":27,"tag":51,"props":3398,"children":3399},{},[3400],{"type":27,"tag":588,"props":3401,"children":3402},{"href":608},[3403],{"type":33,"value":611},{"type":27,"tag":51,"props":3405,"children":3406},{},[3407],{"type":27,"tag":588,"props":3408,"children":3409},{"href":617},[3410],{"type":33,"value":620},{"title":7,"searchDepth":622,"depth":622,"links":3412},[3413,3414,3415,3416,3417,3418,3419,3420,3421,3426],{"id":30,"depth":625,"text":34},{"id":74,"depth":625,"text":77},{"id":211,"depth":625,"text":214},{"id":255,"depth":625,"text":258},{"id":308,"depth":625,"text":311},{"id":365,"depth":625,"text":368},{"id":399,"depth":625,"text":402},{"id":451,"depth":625,"text":454},{"id":538,"depth":625,"text":541,"children":3422},[3423,3424,3425],{"id":545,"depth":622,"text":548},{"id":556,"depth":622,"text":559},{"id":567,"depth":622,"text":570},{"id":578,"depth":625,"text":578},1775441244259]