发布· 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' })