設定

Angular 工作區設定

位於 Angular 工作區根層級的 angular.json 檔案，提供工作區層級與專案專屬的設定預設值。這些設定會供 Angular CLI 提供的建置與開發工具使用。 設定中給定的路徑值，都是相對於工作區根目錄。

一般 JSON 結構

在 angular.json 的最上層，有幾個屬性用來設定工作區，而 projects 區段則包含其餘的各專案設定選項。 你可以透過專案層級的預設值，覆寫在工作區層級設定的 Angular CLI 預設值。 你也可以使用命令列，覆寫在專案層級設定的預設值。

檔案最上層的下列屬性，用來設定工作區。

屬性 詳細說明
version 設定檔版本。
newProjectRoot 透過 ng generate application 或 ng generate library 等工具建立新專案的路徑。路徑可以是絕對路徑，或相對於工作區目錄。預設值為 projects
cli 一組用來自訂 Angular CLI 的選項。請參閱下方的 Angular CLI 設定選項。
schematics 一組原理圖，用來自訂此工作區的 ng generate 子指令選項預設值。請參閱下方的原理圖。
projects 包含工作區中每個應用程式或函式庫的子區段，並帶有專案專屬的設定選項。

你使用 ng new app-name 建立的初始應用程式，會列在 "projects" 之下：

當你使用 ng generate library 建立函式庫專案時，該函式庫專案也會加入 projects 區段。

HELPFUL: 設定檔的 projects 區段，與工作區檔案結構並不完全對應。

  • 由 ng new 建立的初始應用程式，位於工作區檔案結構的最上層。
  • 其他應用程式與函式庫，預設位於 projects 目錄之下。

更多資訊，請參閱工作區與專案檔案結構。

Angular CLI 設定選項

下列屬性是一組用來自訂 Angular CLI 的選項。

屬性 詳細說明 值型別 預設值
analytics 與 Angular 團隊分享匿名使用資料。布林值表示是否分享資料；UUID 字串則會使用假名識別碼分享資料。 boolean | string false
cache 控制 Angular CLI 建置器 使用的持久磁碟快取。 快取選項 {}
schematicCollections 列出要在 ng generate 中使用的原理圖集合。 string[] []
packageManager 要使用的偏好套件管理工具。 npm | pnpm | yarn | bun npm
warnings 控制 Angular CLI 專屬的主控台警告。 警告選項 {}

快取選項

屬性 詳細說明 值型別 預設值
enabled 設定是否為建置啟用磁碟快取。 boolean true
environment 設定在哪種環境中啟用磁碟快取。

_ ci 僅在持續整合（CI）環境中啟用快取。
_ local 僅在 CI 環境 之外 啟用快取。
* all 在所有地方啟用快取。		 local | ci | all local
path 用來儲存快取結果的目錄。 string .angular/cache

警告選項

屬性 詳細說明 值型別 預設值
versionMismatch 當全域 Angular CLI 版本比本地版本新時，顯示警告。 boolean true

專案設定選項

下列最上層設定屬性可用於每個專案，位於 projects['project-name'] 之下。

屬性 詳細說明 值型別 預設值
root 此專案檔案的根目錄，相對於工作區目錄。初始應用程式此值為空，它位於最上層。 string 無（必填）
projectType "application" 或 "library" 其中之一。應用程式可以在瀏覽器中獨立執行，函式庫則不行。 application | library 無（必填）
sourceRoot 此專案原始檔案的根目錄。 string ''
prefix 使用 ng generate 產生新元件、指令與管道時，Angular 會在此字串後加上前綴作為選擇器前綴。可以自訂，以識別某個應用程式或功能領域。 string 'app'
i18n 專案的國際化選項。定義原始語言地區與要建置的其他語言地區。請參閱在建置設定中定義語言地區。 請參閱 i18n 選項 {}
schematics 一組原理圖，用來自訂此專案的 ng generate 子指令選項預設值。請參閱產生原理圖區段。 請參閱原理圖 {}
architect 此專案的 Architect 建置器目標的設定預設值。 請參閱設定建置器目標 {}

i18n 選項

使用 i18n 專案選項，定義應用程式的原始語言地區與要建置的任何其他語言地區。

屬性 詳細說明 值型別 預設值
sourceLocale 應用程式原始碼中使用的語言地區。可以是語言地區識別碼字串，或是一個設定物件。 string | sourceLocale 物件 "en-US"
locales 語言地區識別碼對應到翻譯檔案或語言地區設定物件的對應表。 object {}

sourceLocale 物件

傳入物件而非字串，以自訂原始語言地區的輸出目錄或基底 HREF：

屬性 詳細說明 值型別 預設值
code 原始語言地區識別碼。 string "en-US"
baseHref 覆寫此語言地區的 HTML <base href>。輸出目錄名稱仍保持為語言地區代碼。不能與 subPath 一起使用。 string 語言地區代碼
subPath 同時設定輸出目錄名稱與此語言地區的 HTML <base href>。不能與 baseHref 一起使用。 string 語言地區代碼

語言地區物件

每個 locales 項目可以是路徑字串、路徑陣列或物件：

屬性 詳細說明 值型別 預設值
translation 此語言地區的翻譯檔案路徑（一個或多個）。 string | string[]
baseHref 覆寫此語言地區的 HTML <base href>。輸出目錄名稱仍保持為語言地區識別碼。不能與 subPath 一起使用。 string 語言地區代碼
subPath 同時設定輸出目錄名稱與此語言地區的 HTML <base href>。不能與 baseHref 一起使用。 string 語言地區代碼

HELPFUL: 當你也需要重新命名輸出目錄時，請使用 subPath 而非 baseHref，例如輸出到 de-DE/ 而不是 de/。

原理圖

Angular 原理圖 是一組指示，用來透過加入新檔案或修改現有檔案來修改專案。 你可以將原理圖名稱對應到一組預設選項，藉此進行設定。

原理圖的「名稱」格式為：<schematic-package>:<schematic-name>。 預設 Angular CLI ng generate 子指令的原理圖，收集在套件 @schematics/angular 中。 例如，使用 ng generate component 產生元件的原理圖是 @schematics/angular:component。

原理圖結構定義中給定的欄位，對應到 Angular CLI 子指令選項允許的命令列引數值與預設值。 你可以更新工作區結構定義檔案，為子指令選項設定不同的預設值。例如，若要預設在 ng generate component 中停用 standalone：

{
  "projects": {
    "my-app": {
      "schematics": {
        "@schematics/angular:component": {
          "standalone": false
        }
      }
    }
  }
}

設定 CLI 建置器

Architect 是 Angular CLI 用來執行複雜工作的工具，例如編譯與測試執行。 Architect 是一個殼層，會依照目標設定，執行指定的建置器來完成給定的工作。 你可以定義與設定新的建置器與目標，藉此擴充 Angular CLI。 請參閱 Angular CLI 建置器。

預設的 Architect 建置器與目標

Angular 定義了預設建置器，供特定指令使用，或搭配一般的 ng run 指令使用。 定義每個建置器的選項與預設值的 JSON 結構定義，收集在 @angular/build 套件中。 這些結構定義為下列建置器設定選項。

設定建置器目標

angular.json 的 architect 區段包含一組 Architect 目標。 許多目標對應到執行它們的 Angular CLI 指令。 其他目標可以使用 ng run 指令執行，你也可以定義自己的目標。

每個目標物件會指定該目標的 builder，也就是 Architect 所執行工具的 npm 套件。 每個目標也有一個 options 區段，用來設定該目標的預設選項；以及一個 configurations 區段，用來命名並指定該目標的替代設定。 請參閱下方的 Build target 範例。

屬性 詳細說明
build 設定 ng build 指令選項的預設值。更多資訊，請參閱 Build target 區段。
serve 設定 ng serve 指令選項的預設值。開發伺服器有自己的選項，並會使用其 buildTarget 選項中設定的建置目標來建置應用程式。
e2e 設定 ng e2e 指令選項的預設值，該指令會執行端對端測試。ng new 不會產生此目標。在沒有此目標的情況下執行 ng e2e，會提供加入端對端測試套件的選項。
test 設定 ng test 指令選項的預設值。單元測試建置器會使用其 buildTarget 選項中設定的建置目標來建置測試。
lint 設定 ng lint 指令選項的預設值，該指令會對專案原始檔案執行靜態程式碼分析。ng new 不會產生此目標。在沒有此目標的情況下執行 ng lint，會提供加入 angular-eslint 的選項。
extract-i18n 設定 ng extract-i18n 指令選項的預設值，該指令會從原始碼擷取本地化訊息字串，並輸出國際化用的翻譯檔案。

HELPFUL: 設定檔中的所有選項都必須使用 camelCase，而不是命令列所使用的 dash-case。

Build target

architect 下的每個目標都有下列屬性：

屬性 詳細說明
builder 用來建立此目標的 CLI 建置器，格式為 <package-name>:<builder-name>。
options 建置目標的預設選項。
configurations 執行目標的替代設定。每個設定會為其預期環境設定預設選項，覆寫 options 下的相關值。請參閱下方的替代建置設定。

例如，若要設定停用最佳化的建置：

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "optimization": false
          }
        }
      }
    }
  }
}

替代建置設定

Angular CLI 附帶兩種建置設定：production 與 development。 預設情況下，ng build 指令使用 production 設定，這會套用多項建置最佳化，包括：

  • 打包檔案
  • 將多餘空白降到最低
  • 移除註解與無用程式碼
  • 將程式碼最小化，使用簡短且經名稱混淆處理的名稱

你可以定義並命名額外的替代設定（例如 staging），以符合你的開發流程。 你可以將替代設定的名稱傳給 --configuration 命令列旗標，藉此選取替代設定。

例如，若要設定僅在生產建置時才啟用最佳化（ng build --configuration production）：

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "optimization": false
          },
          "configurations": {
            "production": {
              "optimization": true
            }
          }
        }
      }
    }
  }
}

你也可以以逗號分隔清單的形式傳入多個設定名稱。 例如，若要同時套用 staging 與 french 建置設定，請使用指令 ng build --configuration staging,french。 在這種情況下，指令會由左至右解析命名的設定。 若多個設定變更了相同設定，最後設定的值就是最終值。 在此範例中，若 staging 與 french 設定都設定了輸出路徑，將會使用 french 中的值。

額外的建置與測試選項

預設或目標建置的可設定選項，通常對應到 ng build 與 ng test 指令可用的選項。 這些選項與其可能值的詳細資訊，請參閱 Angular CLI 參考文件。

選項屬性 詳細說明
assets 包含要隨應用程式提供的靜態資產路徑的物件。預設路徑指向專案的 public 目錄。更多資訊，請參閱資產設定區段。
styles 要加入專案全域脈絡的 CSS 檔案陣列。Angular CLI 支援 CSS 匯入與所有主要的 CSS 預處理器。更多資訊，請參閱樣式與指令碼設定區段。
stylePreprocessorOptions 包含要傳給樣式預處理器的選項與值配對的物件。請參閱樣式與指令碼設定區段。
inlineStyleLanguage 應用程式的行內元件樣式所使用的樣式表語言。接受 css、less、sass 或 scss，預設值是 css。
scripts 包含要加入應用程式的 JavaScript 檔案的物件。這些指令碼的載入方式，就完全如同你在 index.html 內的 <script> 標籤中所加入的一樣。更多資訊，請參閱樣式與指令碼設定區段。
budgets 應用程式全部或部分的預設大小預算型別與閾值。你可以設定建置器，在輸出達到或超過閾值大小時回報警告或錯誤。請參閱設定大小預算。
fileReplacements 包含檔案及其編譯時期替代項的物件。更多資訊，請參閱設定目標專屬檔案替代。
index 載入應用程式的基底 HTML 文件。更多資訊，請參閱索引設定。
security 設定安全性功能的物件。更多資訊，請參閱安全性設定區段。

額外的 serve 選項

開發伺服器有自己的一組選項，大致對應到 ng serve 指令可用的選項。

選項屬性 詳細說明
allowedHosts 開發伺服器會回應的主機陣列。此選項會設定同名的 Vite 選項。更多詳細資訊，請參閱 Vite 文件

複雜設定值

assets、index、outputPath、styles 與 scripts 選項，可以是簡單的路徑字串值，也可以是帶有特定欄位的物件值。 sourceMap 與 optimization 選項可以設為簡單的布林值。它們也可以使用設定檔給定複雜值。

下列區段提供更多關於這些複雜值在各情況下如何使用的詳細資訊。

資產設定

每個 build 目標設定都可以包含一個 assets 陣列，列出你想在建置專案時原樣複製的檔案或資料夾。 預設情況下，public/ 目錄的內容會被複製過去。

若要排除某項資產，你可以將它從 assets 設定中移除。

你可以進一步將資產指定為物件（而不是相對於工作區根目錄的簡單路徑），藉此設定要複製的資產。 資產規格物件可以有下列欄位。

欄位 詳細說明
glob 以 input 作為基底目錄的 node-glob。
input 相對於工作區根目錄的路徑。
output 相對於 outDir 的路徑。由於安全性考量，Angular CLI 絕不會將檔案寫入專案輸出路徑之外。
ignore 要排除的 glob 清單。
followSymlinks 允許 glob 模式跟隨符號連結目錄。這讓符號連結的子目錄也能被搜尋。預設值為 false。

例如，下列資產物件將 src/assets/ 的內容複製到 /assets/，並將 src/favicon.ico 複製到輸出根目錄。

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "src/assets/",
                "output": "/assets/"
              },
              {
                "glob": "favicon.ico",
                "input": "src/",
                "output": "/"
              }
            ]
          }
        }
      }
    }
  }
}

下列範例使用 ignore 欄位，將 assets 目錄中的某些檔案排除在建置複製之外：

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "src/assets/",
                "ignore": ["**/*.svg"],
                "output": "/assets/"
              }
            ]
          }
        }
      }
    }
  }
}

樣式與指令碼設定

styles 與 scripts 選項的陣列項目，可以是簡單路徑字串，或是指向額外進入點檔案的物件。 相關建置器會在建置期間，將該檔案及其相依性載入為個別的套件組。 使用設定物件時，你可以選擇使用 bundleName 欄位，為進入點的套件組命名。

套件組預設會被注入，但你可以將 inject 設為 false，將套件組排除在注入之外。 例如，下列物件值會建立並命名一個包含樣式與指令碼的套件組，並將其排除在注入之外：

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "styles": [
              {
                "input": "src/external-module/styles.scss",
                "inject": false,
                "bundleName": "external-module"
              }
            ],
            "scripts": [
              {
                "input": "src/external-module/main.js",
                "inject": false,
                "bundleName": "external-module"
              }
            ]
          }
        }
      }
    }
  }
}

樣式預處理器選項

在 Sass 中，元件樣式與全域樣式都可以使用 includePaths 功能。這讓你可以加入額外的基底路徑，在匯入時進行檢查。

若要加入路徑，請使用 stylePreprocessorOptions 選項：

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "stylePreprocessorOptions": {
              "includePaths": ["src/style-paths"]
            }
          }
        }
      }
    }
  }
}

該目錄中的檔案（例如 src/style-paths/_variables.scss），可以從專案中的任何位置匯入，無需使用相對路徑：

src/app/app.scss

// A relative path works
@import '../style-paths/variables';

// But now this works as well
@import 'variables';

HELPFUL: 預設的 @angular/build:unit-test 建置器沒有 styles 或 scripts 選項。它會從其 buildTarget 選項所設定的建置目標繼承 styles 與 stylePreprocessorOptions，但不會繼承 scripts。 若要在單元測試之前執行指令碼，請將它加入 test 目標的 setupFiles 選項。 若你的專案使用 @angular/build:karma 建置器，請將單元測試需要的任何樣式或指令碼加入 test 目標。 另請參閱在應用程式中使用執行階段全域函式庫。

最佳化設定

optimization 選項可以是布林值，也可以是物件，以進行更細緻的設定。 此選項會啟用建置輸出的多項最佳化，包括：

有幾個選項可用來微調應用程式的最佳化。

選項 詳細說明 值型別 預設值
scripts 啟用指令碼輸出的最佳化。 boolean true
styles 啟用樣式輸出的最佳化。 boolean | 樣式最佳化選項 true
fonts 啟用字型的最佳化。這需要網際網路存取。 boolean | 字型最佳化選項 true

樣式最佳化選項

選項 詳細說明 值型別 預設值
minify 透過移除多餘空白與註解、合併識別碼以及將值最小化，將 CSS 定義最小化。 boolean true
inlineCritical 擷取並行內化關鍵 CSS 定義，以改善首次內容繪製。 boolean true
removeSpecialComments 移除全域 CSS 中包含 @license 或 @preserve，或是以 //! 或 /*! 開頭的註解。 boolean true

字型最佳化選項

選項 詳細說明 值型別 預設值
inline 在應用程式的 HTML 索引檔案中行內化外部 Google Fonts 與 Adobe Fonts CSS 定義，藉此減少會阻擋渲染的請求。這需要網際網路存取。 boolean true

你可以提供如下的值，藉此將最佳化套用到其中一項：

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "optimization": {
              "scripts": true,
              "styles": {
                "minify": true,
                "inlineCritical": true
              },
              "fonts": true
            }
          }
        }
      }
    }
  }
}

來源對應設定

sourceMap 建置器選項可以是布林值，也可以是物件，以進行更細緻的設定，控制應用程式的來源對應。

選項 詳細說明 值型別 預設值
scripts 為所有指令碼輸出來源對應。 boolean true
styles 為所有樣式輸出來源對應。 boolean true
vendor 解析供應商套件的來源對應。 boolean false
hidden 從輸出 JavaScript 中省略來源對應的連結。 boolean false
sourcesContent 在來源對應中輸出檔案的原始原始碼內容。 boolean true

下方的範例示範如何切換一個或多個值，藉此設定來源對應輸出：

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "sourceMap": {
              "scripts": true,
              "styles": false,
              "hidden": true,
              "vendor": true
            }
          }
        }
      }
    }
  }
}

HELPFUL: 使用隱藏的來源對應時，來源對應不會在套件組中被參照。 若你只想讓來源對應在錯誤回報工具中對應堆疊追蹤，而不希望它們出現在瀏覽器開發人員工具中，這會很有用。 請注意，雖然 hidden 可防止來源對應在輸出套件組中被連結，你的部署流程仍必須注意不要在生產環境中提供產生的來源對應，否則資訊仍會外洩。

不含來源內容的來源對應

你可以產生不含 sourcesContent 欄位的來源對應，該欄位包含原始原始碼。 這讓你可以將來源對應部署到生產環境，在使用原始來源名稱進行更好的錯誤回報的同時，保護你的原始碼不外洩。

若要從來源對應中排除來源內容，請將 sourcesContent 選項設為 false：

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "sourceMap": {
              "scripts": true,
              "styles": true,
              "sourcesContent": false
            }
          }
        }
      }
    }
  }
}

索引設定

設定應用程式 HTML 索引的產生方式。

index 選項可以是字串，也可以是物件，以進行更細緻的設定。 將它設為 false，便不會產生 HTML 索引檔案。

以字串形式提供值時，指定路徑的檔案名稱會用於產生的檔案，並會在應用程式設定輸出路徑的根目錄中建立。

索引選項

選項 詳細說明 值型別 預設值
input 要用於應用程式產生的 HTML 索引的檔案路徑。 string 無（必填）
output 應用程式產生的 HTML 索引檔案的輸出路徑。會使用所提供的完整路徑，並會視為相對於應用程式設定的輸出路徑。 string index.html
preloadInitial 為應用程式的初始檔案與資源，產生 preload、modulepreload 與 preconnect 連結元素。 boolean 啟用服務工作程式時為 false，否則為 true

安全性設定

security 選項是一個物件，可啟用個別的安全性功能。

選項 詳細說明
autoCsp 設為 true 時產生以雜湊為基礎的內容安全政策，或設為 {"unsafeEval": true} 以同時允許 eval。請參閱使用 autoCsp 對行內指令碼進行雜湊。
allowedHosts 允許存取伺服器端應用程式的主機名稱。請參閱防止伺服器端請求偽造 (SSRF)。

輸出路徑設定

outputPath 選項可以是字串（會用作 base 值），也可以是物件，以進行更細緻的設定。

有幾個選項可用來微調應用程式的輸出結構。

選項 詳細說明 值型別 預設值
base 指定相對於工作區根目錄的輸出路徑。 string
browser 位於基底輸出路徑之內，你的瀏覽器建置的輸出目錄名稱。這可以安全地提供給使用者。 string browser
server 位於輸出路徑基底之內，你的伺服器建置的輸出目錄名稱。 string server
media 位於輸出瀏覽器目錄之內，你的媒體檔案的輸出目錄名稱。這些媒體檔案在 CSS 檔案中通常被稱為資源。 string media