发布· 2025年9月2日

Nuxt 4.1

Nuxt 4.1 发布了——它带来了增强的构建稳定性、更好的开发体验以及为模块作者提供的强大新功能！

Daniel Roe

@danielroe.dev

🔥 构建和性能改进

🍫 增强的 Chunk 稳定性

通过导入映射（#33075）显著提高了构建稳定性。这可以防止在进行微小更改时可能导致构建大部分失效的级联哈希更改。

<!-- Automatically injected import map -->
<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>

默认情况下，Vite 构建中发出的 JS chunk 会被哈希，这意味着它们可以被不可变地缓存。然而，这可能会导致一个严重的问题：对单个组件的更改可能会导致*每个*哈希都失效，从而大大增加出现 404 的可能性。

简而言之

组件略微更改 - 其 JS chunk 的哈希值更改
使用该组件的页面必须更新以引用新的文件名
*入口*由于动态导入页面而使其哈希值更改
*所有其他文件* 由于入口文件名更改而使其哈希值更改

显然，这并不是最优的。通过这个新功能，导入入口的（否则）未更改文件的哈希值将不会受到影响。

此功能自动启用，有助于在生产环境中保持更好的缓存效率。它确实需要原生导入映射支持，但如果您将 vite.build.target 配置为包含不支持导入映射的浏览器，Nuxt 将自动禁用它。

当然，如果需要，您也可以禁用它。

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    entryImportMap: false
  }
})

🦀 实验性 Rolldown 支持

Nuxt 现在包含了对 rolldown-vite（#31812）的实验性支持，带来了由 Rust 驱动的打包，可能实现更快的构建。

要在 Nuxt 项目中尝试 Rolldown，您需要用 Rolldown 驱动的版本覆盖 Vite，因为 Vite 是 Nuxt 的一个依赖项。将以下内容添加到您的 package.json 中：

{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}

{
  "pnpm": {
    "overrides": {
      "vite": "npm:rolldown-vite@latest"
    }
  }
}

{
  "resolutions": {
    "vite": "npm:rolldown-vite@latest"
  }
}

{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}

添加覆盖后，重新安装您的依赖项。Nuxt 将自动检测 Rolldown 何时可用，并相应地调整其构建配置。

有关 Rolldown 集成的更多详细信息，请参阅Vite Rolldown 指南.

这是实验性的，可能存在一些限制，但它提供了 Nuxt 中高性能打包未来的一瞥。

🧪 改进的延迟水合

延迟水合宏现在无需自动导入即可工作（#33037），这使得它们在组件自动发现被禁用时更加可靠。

<script setup>
// Works even with components: false
const LazyComponent = defineLazyHydrationComponent(
  'visible',
  () => import('./MyComponent.vue')
)
</script>

这确保了那些未通过 Nuxt “发现”的组件（例如，因为配置中 components 设置为 false）仍然可以在延迟水合宏中使用。

📄 增强的页面规则

如果您启用了路由规则的实验性提取，这些规则现在会暴露在 NuxtPage 对象的专用 rules 属性上（#32897），使模块更容易访问它们并改进整体架构。

// In your module
nuxt.hook('pages:extend', pages => {
  pages.push({
    path: '/api-docs',
    rules: { 
      prerender: true,
      cors: true,
      headers: { 'Cache-Control': 's-maxage=31536000' }
    }
  })
})

defineRouteRules 函数继续像以前一样工作，但现在为模块提供了更好的集成可能性。

🚀 模块开发增强

🪾 模块依赖和集成

模块现在可以指定依赖项并修改其他模块的选项（#33063）。这实现了更好的模块集成并确保了正确的设置顺序。

export default defineNuxtModule({
  meta: {
    name: 'my-module',
  },
  moduleDependencies: {
    'some-module': {
      // You can specify a version constraint for the module
      version: '>=2',
      // By default moduleDependencies will be added to the list of modules 
      // to be installed by Nuxt unless `optional` is set.
      optional: true,
      // Any configuration that should override `nuxt.options`.
      overrides: {},
      // Any configuration that should be set. It will override module defaults but
      // will not override any configuration set in `nuxt.options`.
      defaults: {}
    }
  },
  setup (options, nuxt) {
    // Your module setup logic
  }
})

这取代了已弃用的 installModule 函数，并提供了一种更强大的方式来处理具有版本约束和配置合并的模块依赖。

🪝 模块生命周期钩子

模块作者现在可以访问两个新的生命周期钩子：onInstall 和 onUpgrade（#32397）。这些钩子允许模块在首次安装或升级到新版本时执行额外的设置步骤。

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    version: '1.0.0',
  },

  onInstall(nuxt) {
    // This will be run when the module is first installed
    console.log('Setting up my-module for the first time!')
  },

  onUpgrade(inlineOptions, nuxt, previousVersion) {
    // This will be run when the module is upgraded
    console.log(`Upgrading my-module from v${previousVersion}`)
  }
})

这些钩子仅在模块元数据中同时提供了 name 和 version 时触发。Nuxt 内部使用 .nuxtrc 文件来跟踪模块版本并触发相应的钩子。（如果您以前没有遇到过，.nuxtrc 文件应该被提交到版本控制中。）

这意味着模块作者可以开始实现他们自己的“设置向导”，以便在安装模块后需要进行一些设置时提供更好的体验。

🙈 增强的文件解析

resolveFiles 的新 ignore 选项（#32858）允许模块作者根据 glob 模式排除特定文件。

// Resolve all .vue files except test files
const files = await resolveFiles(srcDir, '**/*.vue', {
  ignore: ['**/*.test.vue', '**/__tests__/**']
})

📂 层目录工具

一个新的 getLayerDirectories 工具（#33098）提供了一个干净的接口来访问层目录，而无需直接访问私有 API。

import { getLayerDirectories } from '@nuxt/kit'

const layerDirs = await getLayerDirectories(nuxt)
// Access key directories:
// layerDirs.app        - /app/ by default
// layerDirs.appPages   - /app/pages by default
// layerDirs.server     - /server by default
// layerDirs.public     - /public by default

✨ 开发者体验改进

🎱 简化的 Kit 工具

一些 Kit 工具已得到改进，以提供更好的开发者体验。

addServerImports 现在支持单个导入（#32289):

// Before: required array
addServerImports([{ from: 'my-package', name: 'myUtility' }])

// Now: can pass directly
addServerImports({ from: 'my-package', name: 'myUtility' })