---
title: "Nuxt 4.1"
description: "Nuxt 4.1 已发布——带来更强的构建稳定性、更好的开发体验，以及面向模块作者的强大新功能！"
canonical_url: "https://nuxt.zhcndoc.com/blog/v4-1"
---
# Nuxt 4.1

> Nuxt 4.1 已发布——带来更强的构建稳定性、更好的开发体验，以及面向模块作者的强大新功能！

## 🔥 构建与性能改进

### 🍫 增强的 Chunk 稳定性

通过 import map 技术显著提升了构建的稳定性（[#33075](https://github.com/nuxt/nuxt/pull/33075)）。这能够避免由于小改动导致的大范围构建散列哈希变化：

```html
<!-- 自动注入的 import map -->
<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>
```

在 Vite 构建中，生成的 JS chunk 默认会被哈希处理，这意味着它们可以被不可变地缓存。但这会带来一个重大问题：单个组件的改动可能导致 *所有* 哈希文件失效，大大增加 404 错误的风险。

简而言之：

1. 组件轻微变动 —— 该组件 JS chunk 的哈希变更
2. 使用该组件的页面需更新以引用新的文件名
3. *entry* 文件因动态导入该页面而哈希随之改变
4. 导入 entry 的 *其他所有文件* 哈希都被改变

显然，这种情况并不理想。开启此新特性后，导入 entry 的其他未变更文件的哈希将不会受到影响。

该功能默认启用，有助于在生产环境中提升缓存效率。它依赖于 [原生 import map 支持](https://caniuse.com/import-maps)，如果你配置了 `vite.build.target` 包含不支持 import map 的浏览器，Nuxt 会自动禁用此功能。

当然，你也可以根据需要手动禁用：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    entryImportMap: false
  }
})
```

### 🦀 实验性 Rolldown 支持

Nuxt 现已实验性支持 `rolldown-vite`（[#31812](https://github.com/nuxt/nuxt/pull/31812)），这是一款基于 Rust 的打包工具，可带来更快的构建速度。

在 Nuxt 项目中尝试使用 Rolldown，需要通过包覆盖来替换默认的 Vite 版本，因为 Vite 是 Nuxt 的依赖。请在你的 `package.json` 中添加以下配置：

::code-group{sync="pm"}
```json [npm]
{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}
```

```json [pnpm]
{
  "pnpm": {
    "overrides": {
      "vite": "npm:rolldown-vite@latest"
    }
  }
}
```

```json [yarn]
{
  "resolutions": {
    "vite": "npm:rolldown-vite@latest"
  }
}
```

```json [bun]
{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}
```
::

添加覆盖后，重新安装依赖。Nuxt 会自动检测 Rolldown 的可用性，并相应调整构建配置。

有关 Rolldown 集成的更多详情，请参阅 [Vite Rolldown 指南](https://vite.dev/guide/rolldown)。

::note
该功能仍处于实验阶段，可能存在限制，但它预示着 Nuxt 高性能打包的未来方向。
::

## 🧪 改进的懒加载水合（Lazy Hydration）

懒加载水合宏现支持无自动导入的使用情况（[#33037](https://github.com/nuxt/nuxt/pull/33037)），提升了组件自动发现被禁用时的可靠性：

```vue
<script setup>
// 即使 components 配置为 false 也可正常工作
const LazyComponent = defineLazyHydrationComponent(
  'visible',
  () => import('./MyComponent.vue')
)
</script>
```

这保证了即便组件未通过 Nuxt 自动“发现”（例如配置中 `components: false`），仍可在懒加载水合宏中使用。

## 📄 强化的页面规则

如果开启了实验性的路由规则提取，这些规则现在会暴露在 `NuxtPage` 对象上的专属 `rules` 属性中（[#32897](https://github.com/nuxt/nuxt/pull/32897)），提高模块访问的便利性并优化整体架构：

```ts
// 在你的模块中
nuxt.hook('pages:extend', pages => {
  pages.push({
    path: '/api-docs',
    rules: { 
      prerender: true,
      cors: true,
      headers: { 'Cache-Control': 's-maxage=31536000' }
    }
  })
})
```

`defineRouteRules` 函数仍完全兼容，但现在为模块提供了更好的集成可能。

## 🚀 模块开发增强

### 🪾 模块依赖与集成

模块现在可以声明依赖关系，并为其他模块修改配置选项（[#33063](https://github.com/nuxt/nuxt/pull/33063)）。这提高了模块间集成度，并确保正确的安装顺序：

```ts
export default defineNuxtModule({
  meta: {
    name: 'my-module',
  },
  moduleDependencies: {
    'some-module': {
      // 可指定所依赖模块的版本约束
      version: '>=2',
      // 默认情况下，moduleDependencies 会添加到 Nuxt 安装列表，除非标记为 optional。
      optional: true,
      // 任意要覆盖 nuxt.options 的配置
      overrides: {},
      // 将设置的默认配置，会覆盖模块默认，但不会覆盖 nuxt.options 中已有配置。
      defaults: {}
    }
  },
  setup (options, nuxt) {
    // 你的模块初始化逻辑
  }
})
```

该功能用来替代已废弃的 `installModule` 函数，并提供更强大的模块依赖处理能力，支持版本约束和配置合并。

### 🪝 模块生命周期钩子

模块作者现可使用两个新的生命周期钩子：`onInstall` 和 `onUpgrade`（[#32397](https://github.com/nuxt/nuxt/pull/32397)）。这允许模块在首次安装或升级时执行额外的初始化步骤：

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

  onInstall(nuxt) {
    // 模块首次安装时运行
    console.log('首次安装 my-module，开始初始化！')
  },

  onUpgrade(inlineOptions, nuxt, previousVersion) {
    // 模块升级时运行
    console.log(`升级 my-module，从版本 v${previousVersion}`)
  }
})
```

钩子仅在模块元数据中同时提供 `name` 和 `version` 时触发。Nuxt 内部使用 `.nuxtrc` 文件跟踪模块版本并触发对应钩子。（如果未接触过，`.nuxtrc` 文件应提交到版本控制）

::tip
这让模块作者能够实现自定义“设置向导”，在模块安装后需要完成某些设置时提供更佳体验。
::

### 🙈 增强的文件解析

`resolveFiles` 新增 `ignore` 选项（[#32858](https://github.com/nuxt/nuxt/pull/32858)），允许模块作者根据 glob 模式排除指定文件：

```ts
// 解析所有 .vue 文件，排除测试文件
const files = await resolveFiles(srcDir, '**/*.vue', {
  ignore: ['**/*.test.vue', '**/__tests__/**']
})
```

### 📂 层目录工具

全新提供的 `getLayerDirectories` 工具（[#33098](https://github.com/nuxt/nuxt/pull/33098)）让访问层目录更简洁，无需直接使用私有 API：

```ts
import { getLayerDirectories } from '@nuxt/kit'

const layerDirs = await getLayerDirectories(nuxt)
// 访问关键目录：
// layerDirs.app        - 默认 /app/
// layerDirs.appPages   - 默认 /app/pages
// layerDirs.server     - 默认 /server
// layerDirs.public     - 默认 /public
```

## ✨ 开发者体验提升

### 🎱 简化的 Kit 工具

多个 kit 工具得到改进，优化开发体验：

- `addServerImports` 现在支持单条导入参数（[#32289](https://github.com/nuxt/nuxt/pull/32289)）：

```ts
// 以前：必须传数组
addServerImports([{ from: 'my-package', name: 'myUtility' }])

// 现在：可直接传单个对象
addServerImports({ from: 'my-package', name: 'myUtility' })
```

### 🔥 性能优化

本次发布包括以下内部性能提升：

- 路由规则缓存管理优化（[#32877](https://github.com/nuxt/nuxt/pull/32877)）
- 应用清单监听优化（[#32880](https://github.com/nuxt/nuxt/pull/32880)）
- 页面元数据 TypeScript 处理改进（[#32920](https://github.com/nuxt/nuxt/pull/32920)）

## 🐛 重要修复

- 优化 `useFetch` 钩子类型定义（[#32891](https://github.com/nuxt/nuxt/pull/32891)）
- 更好地处理页面元数据中的 TypeScript 表达式（[#32902](https://github.com/nuxt/nuxt/pull/32902), [#32914](https://github.com/nuxt/nuxt/pull/32914)）
- 路由匹配与同步增强（[#32899](https://github.com/nuxt/nuxt/pull/32899)）
- 减少开发环境中 Vue 服务器警告的冗余信息（[#33018](https://github.com/nuxt/nuxt/pull/33018)）
- `<NuxtTime>` 中相对时间计算的改进（[#32893](https://github.com/nuxt/nuxt/pull/32893)）

## ✅ 升级指南

照旧，我们推荐的升级操作是：

```sh
npx nuxt upgrade --dedupe
```

这将刷新你的锁文件，并拉取所有 Nuxt 依赖，尤其是 unjs 生态相关的最新内容。

## 📦 Nuxt 3.19

上述功能同样适用于 **Nuxt 3.19**，它与 v4.1 同步发布。作为对 v3 分支的承诺，我们持续回移兼容的 v4 特性，确保 v3 用户同样能受益最新改进。

如果你仍在使用 Nuxt 3，可升级至 v3.19，以在稳定的 v3 系列中享用全部这些新特性。

## 完整发行说明

::read-more{icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v4.1.0"}
阅读 Nuxt `v4.1.0` 的完整发行说明。
::

::read-more{icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.19.0"}
阅读 Nuxt `v3.19.0` 的完整发行说明。
::

感谢所有贡献者！我们期待看到你利用这些新功能创造出精彩作品。❤️


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.