建议收藏：Nuxt.js 源码解析 | 看完就会写

▌ 技术引导
Nuxt.js 源码解析是了解其运行机制和自定义能力的核心路径。如果你打算深入构建自定义插件或者优化 SSR 渲染流程，直接撸源码是绕不开的坎。2024年往后，社区对 Nuxt 的架构改造越来越频繁，比如 3.x 版本带来的模块系统重构，导致部分旧配置失效，甚至影响模块加载机制。我踩过坑，直接读源码能帮你避开这些陷阱，比如在 app.js 中看到的模块注册逻辑，就比文档更清晰。很多开发者在配置 env 变量时遇到问题，实际上是因为源码中对 env 的处理和你想象的不一样，特别是一些 edge case。直接查看 nuxt.config.js 在 build 时如何被解析，能让你理解为什么某些配置项不会生效。如果你用的是 vue3 + nuxt3，源码中的模块结构和 vue2 有明显区别，必须注意版本对应的实现细节。

▌ 技术参考
一
Nuxt.js 源码的起点是 app.js，它负责初始化整个应用并挂载 Vue 实例。如果你想了解 SSR 是如何工作的，可以定位到 nuxtServerInit 方法，它在 store 中被调用。这个方法的执行顺序和 store 的模块注册顺序一致，如果你自定义了 store 模块，确保在 nuxtServerInit 中处理好异步请求。注意，nuxt.config.js 中的 modules 会按顺序加载，每个模块的 setup 方法会被调用。在 3.x 版本中，模块系统采用 ES Modules，这和 vue2 的 CommonJS 方式完全不同。如果你移植旧模块到新版本，必须检查 module.exports 是否被替换为 export default。

二
在 nuxt.config.js 中，build 选项的配置直接影响 Webpack 的打包方式。比如，设置 build.transpile 为 ['vue'], 可以让 Vue 的源码在构建时被 transpile，避免某些浏览器兼容性问题。但要注意，2025年后的 Vue3 版本不再需要这个配置，除非你使用了某些 legacy 代码。另外，nuxt.config.js 中的 devModules 与 modules 的区别在于，前者仅在开发环境下生效，后者会被打包进生产环境。如果你在开发时使用了某些调试工具，比如 vue-devtools，确保它们出现在 devModules 中，否则不会被加载。生产环境打包时，用 nuxt generate 会比 nuxt build 更快，因为它只生成静态页面。

三
Nuxt.js 在 SSR 过程中会调用 render 方法，该方法位于 nuxt.js 的实例中。如果你想自定义 SSR 的行为，比如修改渲染后的 HTML 内容，可以覆盖 this.$nuxt.render 方法。但需要提醒的是，2025年后，渲染过程被拆分成多个阶段，比如 renderPage 和 renderError。在 renderPage 中，你可以访问到 page 的内容和数据，而在 renderError 中，你需要处理 404 等错误页面。特别注意，如果使用了 vue3 的 Composition API，某些 mixins 可能无法正常工作，需要查看 nuxt3 的源码中如何处理组件的生命周期。

四
在 Nuxt.js 的源码中，页面组件的处理逻辑主要在 pages 目录下，每个页面文件都会被注册成一个路由。你可以在 src/runtime/ 目录下找到 pages 目录的处理代码。2024年的版本中，页面的加载方式被优化成异步加载，这通过 pages 中的异步组件实现。如果你在使用 vue3，页面组件的选项会更偏向 setup 函数，而不是传统的 options 语法。另外，pages 中的文件名会影响路由生成的路径，比如 index.vue 会生成 / 路由，而 about.vue 会生成 /about 路由。但如果你在 pages 中放了子目录，比如 /blog/index.vue，它会生成 /blog 路由，而非 /blog/index。

五
Nuxt 路由的处理逻辑在 src/runtime/router.js 中，这个文件会根据 pages 目录结构动态生成路由。如果你在想修改路由逻辑，比如添加自定义路由守卫，可以在这里进行扩展。2026年，Nuxt 的路由系统引入了路由懒加载机制，通过动态 import() 来加载页面组件，这比之前的同步加载更高效。不过，需要注意，懒加载的路由在 SSR 时不会被预渲染，所以如果你希望某些页面在 SSR 时生效，必须确保它们在 pages 目录中，并且没有被延迟加载。另外，页面路由可以被重定向，这在源码中是通过 router.options.routes 的重定向配置实现的。

六
Nuxt 的模块系统在 nuxt3 中被重构为基于 ES Modules 的方式，这使得模块的注册和加载更加灵活。你可以在 src/runtime/ 目录下找到模块加载的核心逻辑，比如模块的注册函数。2025年后，模块的注册方式从 CommonJS 的 require 转变为 import，这需要你调整模块的导出方式。如果你自定义了一个模块，并想让它在构建时被加载，确保模块文件包含 exports.default，而不是 module.exports。另外，模块的 dependencies 会自动被解析，但如果你想要控制模块的加载顺序，可以在 module.exports 的 configure 函数中使用顺序依赖。记得在 module.exports 中使用 runtime 模块，这样模块只在运行时加载，而不是构建时。

七
插件系统在 Nuxt 中是关键，它通过 src/plugins 目录下的文件来实现。插件会被按顺序注册到 Vue 实例上，2024年后的版本中，插件的注册方式更偏向于使用 Vue.use() 或 Vue.directive()。如果你在使用 nuxt3，可以查看 plugins 目录下的文件是否以 .js 或 .mjs 格式存在，因为 nuxt3 默认使用 ES Modules。插件的执行顺序和配置文件中的插件列表顺序有关，你可以在 nuxt.config.js 中通过 plugins 数组来控制。如果插件包含异步函数，记得使用 await 关键字来处理默认值，否则会导致插件未完全加载就执行。

八
Nuxt 的静态生成功能在 2024年后有了很大变化，generate 方法会根据 pages 中的文件生成静态页面。源码中处理静态生成的代码集中在 src/runtime/generate.js 中。如果你使用了 vue3，静态生成的流程会更加复杂，因为组件的编译和挂载方式不同。在 generate 时，页面组件会被编译成 HTML，为了优化性能，可以使用 generate.sitemap 选项来生成站点地图。不过要注意，某些动态组件在 generate 时无法正确渲染，必须在页面组件中使用 static 选项来标记为静态生成页面。另外，generate 的并发数可以通过 generate.concurrency 来调整，提高构建速度。

九
Nuxt 在处理 SSR 和静态生成时，会使用不同的渲染策略。2024年的版本引入了 renderStrategy 配置，可以设置为 'ssr' 或 'spa'，从而决定页面的渲染方式。如果你在使用 nuxt3，默认是 'ssr'，但可以通过构建命令来强制生成静态页面，比如 nuxt generate。SSR 页面在构建时会执行 render 方法，而 SPA 页面则不会。在源码中，renderStrategy 的逻辑主要在 src/runtime/renderer.js 中。如果你遇到 SSR 页面加载慢的问题，可以尝试将某些页面改为 SPA 模式，以减少服务器端渲染的时间开销。

十
Nuxt 的构建流程中，Webpack 配置是关键部分，它决定了如何打包代码。你可以通过 nuxt.config.js 中的 build 选项来自定义 Webpack 配置。比如，设置 build.extend 为一个函数，可以修改 Webpack 的 chainOptions。在 2025年，Nuxt 引入了对 Webpack5 的支持，这导致一些配置项需要调整，比如 devtool 的设置。如果你使用了某些第三方库，可以在 build.transpile 中指定，确保它们被正确编译。另外，使用 build.optimization.splitChunks 可以优化代码分割，提高加载性能。但要注意，某些模块的加载方式会影响 chunk 的分割，需要结合具体模块的配置来调整。

十一
Nuxt 在处理 SSR 时，会将页面内容写入 HTML 字符串，这一过程主要在 src/runtime/renderer.js 中实现。你可以通过配置 nuxt.config.js 中的 render 选项来控制 HTML 内容，比如设置 render.html 为一个函数，返回自定义的 HTML 字符串。2024年后，Nuxt 优化了这一过程，支持动态 HTML 插入。如果你在使用 vue3，需要确保 HTML 插入的逻辑与 Composition API 兼容。此外，render.html 可以和 serverMiddleware 结合使用，实现更复杂的 HTML 处理逻辑。不过，注意不要在 render.html 中处理复杂的逻辑，这会增加 SSR 的执行时间。

十二
Nuxt 的 serverMiddleware 是一个强大的工具，用于在 SSR 之前或之后处理请求。它的工作原理是在服务器启动时，根据 nuxt.config.js 中的 serverMiddleware 配置，挂载到 Express 应用中。2025年，Nuxt 引入了对 serverMiddleware 的优化，使其支持异步处理。你可以在 nuxt.config.js 中使用 middleware 选项来注册，或者通过 serverMiddleware 数组来指定路径。比如，如果你想做 API 请求的中间处理，可以创建一个 middleware 文件，然后在 serverMiddleware 中引用。需要注意，serverMiddleware 不能和页面路由重叠，否则会导致请求冲突。

十三
Nuxt 的配置项在 nuxt.config.js 中，但部分配置项会被自动解析，比如 modules、plugins、build 等。2024年后，Nuxt 的配置系统增加了对 JSON Schema 的支持，这使得配置项的类型和结构更加规范。在源码中，配置项的解析主要在 src/runtime/config.js 中，它会读取环境变量并合并配置。如果你在使用 devServer，可以配置 devServer.proxy 来设置代理规则，这在开发时非常有用，特别是在处理跨域请求时。但是，代理配置的优先级需要注意，某些模块可能会覆盖你的代理设置，导致请求错误。

十四
Nuxt 的模块加载机制在 2025年被重构，模块的加载方式从 CommonJS 转为 ES Modules。这意味着你不能直接使用 require 来导入模块，而是必须使用 import。模块的注册方式也发生了变化，从 module.exports 转为 export default。在源码中，模块的加载逻辑主要集中在 src/runtime/modules.js 中。如果你在开发一个模块，确保它支持 ES Modules，并且导出一个配置对象。此外，部分模块会根据不同的环境变量进行加载，比如生产环境可能不加载某些开发用模块，你需要检查模块的配置项是否正确，避免在生产环境中遗漏关键功能。

十五
Nuxt 的源码中包含大量的异步逻辑，特别是在模块和插件的加载过程中。如果你在调试时遇到异步问题，可以使用 source map 来追踪问题源头。2024年后，Nuxt 默认生成 source map，并且支持按需加载。你可以在 nuxt.config.js 中设置 sourceMap 为 true 来开启这一功能。不过，需要注意，source map 在生产环境中可能会被禁用，所以如果你在构建时遇到问题，确保在 dev 时启用 source map。另外，模块的异步加载可以通过 dynamic imports 实现，这在源码中被广泛应用，尤其是处理大型项目时，可以显著提升构建速度。