釋出· 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' })