Nuxt 3.16

2025-03-17
607
阅读29分钟

本文为译文，原文链接：https://nuxt.com/blog/v3-16

原文作者：Daniel Roe

发布日期：2025-03-7

全新 Nuxt

向大家介绍 create-nuxt，这是启动 Nuxt 项目的全新工具！

它是 nuxi init 的精简版本，体积仅为原来的六分之一，并且作为一个单独文件打包，所有依赖项都内联其中，以便让你尽可能快速地开始项目。

启动一个新项目非常简单：

npm create nuxt

特别感谢 @cmang 的 beautiful ASCII-art 。

想了解更多关于 Nuxt CLI 的发展方向？请查看我们的路线图 这里，包括我们对 交互式模块选择器 的计划。

Unhead v2

我们已升级到 unhead v2，这是 Nuxt 的 <head> 管理引擎。这个主要版本移除了弃用内容并改进了上下文处理方式： 对于 Nuxt 3 用户，我们提供了一个遗留兼容版本，因此不会出现中断 上下文实现现在通过 Nuxt 本身更加直接

// Nuxt 现在重新导出可组合项，同时正确解析上下文
export function useHead(input, options = {}) {
  const unhead = injectHead(options.nuxt)
  return head(input, { head: unhead, ...options })
}

如果你在应用中直接使用 Unhead，请注意：

从 Nuxt 的自动导入或 #app/composables/head 导入，而不是从 @unhead/vue 直接从 @unhead/vue 导入可能会丢失异步上下文

不过别担心 - 我们在 Nuxt 3 中保持了向后兼容性，因此大多数用户无需更改任何内容！

如果你已选择 compatibilityVersion: 4，请查看 我们的升级指南 了解其他更改。

Devtools v2 升级

Nuxt Devtools 已升级到 v2 (#30889)！

你会爱上这些新功能，比如自定义编辑器选择、用于检查已解析配置的 Discovery.js（完美用于调试）、架构生成器的回归以及更精简的依赖项。

我们最喜欢的改进之一是能够跟踪模块如何修改你的 Nuxt 配置 - 让你对底层发生的事情有 X 射线般的洞察力。

在 Nuxt DevTools 发布说明 中发现所有详细信息。

性能提升

我们继续让 Nuxt 变得更快，v3.16 中有许多改进：

  1. 使用 exsolve 进行模块解析 (#31124)，以及 unjs 生态系统的其余部分（nitro、c12、pkg-types 等） - 这极大地加快了模块解析速度
  2. 更智能的模块解析路径 (#31037) - 优先直接导入以提高效率
  3. 消除了重复的 Nitro 别名解析 (#31088) - 更精简的文件处理
  4. 通过跳过不必要的解析步骤来优化 loadNuxt(#31176) - 更快的启动
  5. 在 Nuxt 插件中采用 oxc-parser 进行解析(#30066)

所有这些加速改进都会自动生效 - 无需任何配置！

感谢 CodSpeed 使用 Vitest benchmarking 在 CI 中测量这些改进 - 这非常有帮助。

为了增加一些轶事证据，我个人的网站 roe.dev 在使用 v3.16 时加载速度提高了 32%，而 nuxt.com 则提高了 28%。希望你能看到类似的结果！

延迟水合支持

我们很高兴为你带来原生延迟/懒加载水合支持 (#26468)！这让你可以精确控制组件在何时进行水合，从而改善初始加载性能和交互时间。我们利用了 Vue 的内置水合策略 - 在 Vue 文档中查看它们。

<template>
  <!-- 当组件在视口中可见时进行水合 -->
  <LazyExpensiveComponent hydrate-on-visible />
  
   <!-- 当浏览器空闲时进行水合 -->
  <LazyHeavyComponent hydrate-on-idle />
  
  <!-- 在交互时（此处为鼠标悬停）进行水合 -->
  <LazyDropdown hydrate-on-interaction="mouseover" />
  
  <!-- 当媒体查询匹配时进行水合 -->
  <LazyMobileMenu hydrate-on-media-query="(max-width: 768px)" />
  
  <!-- 在特定延迟（以毫秒为单位）后进行水合 -->
  <LazyFooter :hydrate-after="2000" />
</template>

你还可以通过 @hydrated 事件来监听水合发生的时间：

<LazyComponent hydrate-on-visible @hydrated="onComponentHydrated" />

在 我们的组件文档 中了解更多关于懒加载水合的信息。

高级页面配置

你现在可以精细调整 Nuxt 扫描页面文件的方式 (#31090)，从而让你对项目结构有更多控制：

export default defineNuxtConfig({
  pages: {
     // 筛选特定文件或目录
    pattern: ['**/*.vue'],
  }
})

增强调试

我们使使用 debug 选项进行调试更加灵活！现在你可以启用所需的特定调试日志 (#30578)：

export default defineNuxtConfig({
  debug: {
    // 启用特定的调试功能
    templates: true,
    modules: true,
    watchers: true,
    hooks: {
      client: true,
      server: true,
    },
    nitro: true,
    router: true,
    hydration: true,
  }
})

或者使用 debug: true 简单地启用所有这些调试功能。

装饰器支持

对于装饰器爱好者（无论你是谁！），我们添加了实验性支持 (#27672)。与所有实验性功能一样，非常欢迎反馈。

export default defineNuxtConfig({
  experimental: {
    decorators: true
  }
})

function something (_method: () => unknown) {
  return () => 'decorated'
}

class SomeClass {
  @something
  public someMethod () {
    return 'initial'
  }
}

const value = new SomeClass().someMethod()
// 返回 'decorated'

命名层别名

这是大家期待已久的功能，现在它来了！自动扫描的本地层（来自你的 ~~/layers 目录）现在会自动创建别名。你可以通过 #layers/test 访问你的 ~~/layers/test 层 (#30948) - 无需任何配置。

如果你想为其他层设置命名别名，可以在层配置中添加名称：

export default defineNuxtConfig({
  $meta: {
    name: 'example-layer',
  },
})

这将创建别名 #layers/example-layer 指向你的层 - 让导入更加简洁和直观。

错误处理改进

我们大大改进了错误消息和源码跟踪 (#31144)：

  1. 对未定义的 useAsyncData 调用提供更好的警告，并附上精确的文件位置信息
  2. 岛页错误时错误页面现在能正确显示(#31081)

此外，我们现在使用 Nitro 的漂亮错误处理（由 youch 提供支持）来在终端中提供更有帮助的错误消息，包括堆栈跟踪支持。

Nitro 现在还会自动应用源映射，无需额外的 Node 选项，并且在渲染错误页面时我们设置了适当的安全头。

模块开发改进

对于模块作者，我们添加了通过 addTypeTemplate 增强 Nitro 类型的能力 (#31079)：

// 在你的 Nuxt 模块中
export default defineNuxtModule({
  setup(options, nuxt) {
    addTypeTemplate({
      filename: 'types/my-module.d.ts',
      getContents: () => `
        declare module 'nitropack' {
          interface NitroRouteConfig {
            myCustomOption?: boolean
          }
        }
      `
    }, { nitro: true })
  }
})

Nitro v2.11 升级

我们已升级到 Nitro v2.11。改进之处众多，无法在此简短的发行说明中一一涵盖。 在 Nitro v2.11.0 发行说明 中查看所有详细信息。

新的 unjs 主要版本

此版本包含来自 unjs 生态系统的多个主要版本升级，重点通过仅 ESM 分发实现性能提升和更小的打包体积：

-unenv 升级到 v2（全面重写） -db0 升级到 v0.3（仅 ESM，原生 node:sql，改进） -ohash 升级到 v2（仅 ESM，原生 node:crypto 支持，速度大幅提升） -untyped 升级到 v2（仅 ESM，安装体积更小） -unimport 升级到 v4（改进） -c12 升级到 v3（仅 ESM） -pathe 升级到 v2（仅 ESM） -cookie-es 升级到 v2（仅 ESM） -esbuild 升级到 v0.25 -chokidar 升级到 v4

升级

像往常一样，我们推荐的升级方式是运行：

npx nuxi@latest upgrade --dedupe

这将刷新你的 lockfile 并拉取 Nuxt 依赖的所有最新依赖项，特别是来自 unjs 生态系统的依赖项。

完整发行说明

https://github.com/nuxt/nuxt/releases/tag/v3.16.0

向所有参与此次发行的人致以诚挚的感谢。

评论