編寫 Nuxt 層

Nuxt 提供了一個強大的系統，允許您擴充套件預設檔案、配置等等。

Nuxt 層是一個強大的功能，您可以使用它在 monorepo 中，或從 Git 倉庫或 npm 包中共享和重用部分 Nuxt 應用程式。層的結構幾乎與標準 Nuxt 應用程式相同，這使得它們易於創作和維護。

在文件 > 4 X > 入門 > 層中閱讀更多內容。

一個最小的 Nuxt 層目錄應包含一個 nuxt.config.ts 檔案，以表明它是一個層。

base/nuxt.config.ts
export default defineNuxtConfig({})

此外，層目錄中的某些其他檔案將被 Nuxt 自動掃描並用於擴充套件此層的專案。

基本示例

export default defineNuxtConfig({
  extends: [
    './base',
  ],
})

層優先順序

當從多個層擴充套件時，瞭解優先順序順序很重要

  1. extends 中的層 - 較早的條目具有較高優先順序（第一個覆蓋第二個）
  2. 按字母順序（Z 覆蓋 A）從 ~~/layers 目錄中自動掃描的本地層
  3. 您的專案在堆疊中具有最高優先順序 - 它將始終覆蓋其他層

例如

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    // Highest priority (among extends)
    './layers/base',
    // Medium priority
    './layers/theme',
    // Lower priority
    './layers/custom',
  ],
  // Your project has the highest priority
})

如果您還有自動掃描的層，例如 ~~/layers/a 和 ~~/layers/z，則完整的覆蓋順序將是：base > theme > custom > z > a > 您的專案。

入門模板

要開始使用，您可以使用nuxt/starter/layer 模板初始化一個層。這將建立一個您可以基於其構建的基本結構。在終端中執行此命令以開始使用

終端
npm create nuxt -- --template layer nuxt-layer

遵循 README 說明以瞭解後續步驟。

釋出層

您可以透過使用遠端源或 npm 包來發布和共享層。

Git 倉庫

您可以使用 Git 倉庫共享您的 Nuxt 層。一些示例：

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    // GitHub Remote Source
    'github:username/repoName',
    // GitHub Remote Source within /base directory
    'github:username/repoName/base',
    // GitHub Remote Source from dev branch
    'github:username/repoName#dev',
    // GitHub Remote Source from v1.0.0 tag
    'github:username/repoName#v1.0.0',
    // GitLab Remote Source example
    'gitlab:username/repoName',
    // Bitbucket Remote Source example
    'bitbucket:username/repoName',
  ],
})
如果您想擴充套件私有遠端源，您需要新增環境變數 GIGET_AUTH=<token> 以提供令牌。
如果您想從自託管的 GitHub 或 GitLab 例項擴充套件遠端源，您需要使用 GIGET_GITHUB_URL=<url> 或 GIGET_GITLAB_URL=<url> 環境變數提供其 URL - 或直接透過您 nuxt.config 中的 auth 選項進行配置。
請記住，如果您將遠端源作為層擴充套件，您將無法在 Nuxt 之外訪問其依賴項。例如，如果遠端層依賴於 eslint 外掛，則該外掛將無法在您的 eslint 配置中使用。這是因為這些依賴項將位於一個特殊位置（node_modules/.c12/layer_name/node_modules/），您的包管理器無法訪問。
當使用 Git 遠端源時，如果一個層有 npm 依賴項並且您希望安裝它們，您可以透過在層選項中指定 install: true 來實現。
nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    ['github:username/repoName', { install: true }],
  ],
})

npm 包

您可以將 Nuxt 層釋出為 npm 包，其中包含您想要擴充套件的檔案和依賴項。這允許您與他人共享您的配置，在多個專案中使用它或私下使用它。

要從 npm 包擴充套件，您需要確保模組已釋出到 npm 並作為 devDependency 安裝在使用者的專案中。然後您可以使用模組名稱來擴充套件當前的 nuxt 配置。

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    // Node Module with scope
    '@scope/moduleName',
    // or just the module name
    'moduleName',
  ],
})

要將層目錄釋出為 npm 包，您需要確保 package.json 具有正確填充的屬性。這將確保檔案在包釋出時被包含。

package.json
{
  "name": "my-theme",
  "version": "1.0.0",
  "type": "module",
  "main": "./nuxt.config.ts",
  "dependencies": {},
  "devDependencies": {
    "nuxt": "^3.0.0"
  }
}
確保層中匯入的任何依賴項都明確新增到 dependencies 中。nuxt 依賴項以及僅用於在釋出前測試層的任何內容應保留在 devDependencies 欄位中。

現在您可以繼續將模組釋出到 npm，無論是公開還是私下。

當將層釋出為私有 npm 包時，您需要確保登入以透過 npm 進行身份驗證以下載節點模組。

提示

命名層別名

自動掃描的層（來自您的 ~~/layers 目錄）會自動建立別名。例如，您可以透過 #layers/test 訪問您的 ~~/layers/test 層。

如果您想為其他層建立命名層別名，可以在層的配置中指定一個名稱。

nuxt.config.ts
export default defineNuxtConfig({
  $meta: {
    name: 'example',
  },
})

這將生成一個指向您的層的別名 #layers/example。

相對路徑和別名

當在層元件和組合式函式中使用全域性別名（例如 ~/ 和 @/）匯入時，請注意這些別名是相對於使用者專案路徑解析的。作為一種變通方法，您可以使用相對路徑匯入它們，或使用命名層別名。

此外，當在層的 nuxt.config 檔案中使用相對路徑時（巢狀的 extends 除外），它們是相對於使用者專案而不是層解析的。作為一種變通方法，請在 nuxt.config 中使用完整的解析路徑。

nuxt.config.ts
import { fileURLToPath } from 'node:url'
import { dirname, join } from 'node:path'

const currentDir = dirname(fileURLToPath(import.meta.url))

export default defineNuxtConfig({
  css: [
    join(currentDir, './app/assets/main.css'),
  ],
})

Nuxt 模組的多層支援

您可以使用內部陣列 nuxt.options._layers 來支援模組的自定義多層處理。

modules/my-module.ts
export default defineNuxtModule({
  setup (_options, nuxt) {
    for (const layer of nuxt.options._layers) {
      // You can check for a custom directory existence to extend for each layer
      console.log('Custom extension for', layer.cwd, layer.config)
    }
  },
})

注意事項

  • _layers 陣列中較早的專案具有較高優先順序並覆蓋較晚的專案
  • 使用者的專案是 _layers 陣列中的第一個專案

深入瞭解

配置載入和擴充套件支援由unjs/c12處理，使用unjs/defu合併，並使用unjs/giget支援遠端 Git 源。檢視文件和原始碼以瞭解更多資訊。

在 GitHub 上檢視我們正在進行的開發，以帶來更多層支援的改進。