Конфигурация рабочего пространства Angular¶

28.02.2022

Файл angular.json на корневом уровне рабочего пространства Angular workspace предоставляет настройки по умолчанию для всего рабочего пространства и конкретного проекта. Они используются для инструментов сборки и разработки, предоставляемых Angular CLI. Значения путей, указанные в конфигурации, относятся к корневому каталогу рабочего пространства.

Общая структура JSON¶

На верхнем уровне angular.json несколько свойств конфигурируют рабочее пространство, а раздел projects содержит остальные параметры конфигурации для каждого проекта. Вы можете переопределить параметры по умолчанию Angular CLI, установленные на уровне рабочего пространства, через параметры по умолчанию, установленные на уровне проекта.

Вы также можете отменить значения по умолчанию, установленные на уровне проекта, используя командную строку.

Следующие свойства, расположенные на верхнем уровне файла, настраивают рабочее пространство.

Свойства	Подробности
`version`	Версия конфигурационного файла.
`newProjectRoot`	Путь, где создаются новые проекты. Абсолютный или относительный к каталогу рабочей области.
`cli`	Набор опций, настраивающих Angular CLI. См. раздел Angular CLI configuration options.
`schematics`	Набор schematics, которые настраивают параметры по умолчанию подкоманды `ng generate` для данного рабочего пространства. См. раздел Generation schematics.
`projects`	Содержит подраздел для каждой библиотеки или приложения в рабочем пространстве, с опциями конфигурации для каждого проекта.

Первоначальное приложение, которое вы создаете с помощью команды ng new app_name, находится в списке "projects":

"projects": {
  "app_name": {
    // …
  }
  // …
}

Когда вы создаете проект библиотеки с помощью ng generate library, проект библиотеки также добавляется в раздел projects.

Секция projects конфигурационного файла не совсем соответствует структуре файлов рабочей области.

Начальное приложение, создаваемое командой ng new, находится на верхнем уровне файловой структуры рабочей области.
Другие приложения и библиотеки помещаются в каталог projects рабочей области.

Более подробная информация приведена в разделе Файловая структура рабочего пространства и проектов.

Параметры конфигурации Angular CLI¶

Следующие свойства конфигурации представляют собой набор опций, которые настраивают Angular CLI.

Свойство	Детали	Тип значения
`analytics`	Поделиться анонимными данными об использовании с командой Angular Team.	`boolean` \| `ci`
`cache`	Управление постоянным дисковым кэшем, используемым Angular CLI Builders.	Опции кэша
`schematicCollections`	Список коллекций схем по умолчанию для использования.	`string[]`
`packageManager`	Предпочтительный инструмент менеджера пакетов для использования.	`npm` \| `cnpm` \| `pnpm` \|`yarn`
`warnings`	Управление предупреждениями консоли, специфичными для Angular CLI.	Warnings options

Опции кэша¶

Свойство	Подробности	Тип значения	Значение по умолчанию
`enabled`	Настройка того, включено ли кэширование дисков.	`boolean`	`true`
`environment`	Настройте, в каком окружении включено дисковое кэширование.	`local` \| `ci` \| `all`	`local`
`path`	Каталог, используемый для хранения результатов кэширования.	`string`	`.angular/cache`

Параметры предупреждений¶

Свойство	Детали	Тип значения	Значение по умолчанию
`versionMismatch`	Показывать предупреждение, когда глобальная версия Angular CLI новее локальной.	`boolean`	`true`

Параметры конфигурации проекта¶

Следующие свойства конфигурации верхнего уровня доступны для каждого проекта в разделе projects:<имя_проекта>.

"my-app": {
  "root": "",
  "sourceRoot": "src",
  "projectType": "application",
  "prefix": "app",
  "schematics": {},
  "architect": {}
}

Свойство	Детали
`root`	Корневой каталог для файлов этого проекта, относительно каталога рабочего пространства. Пустой для начального приложения, которое находится на верхнем уровне рабочего пространства.
`sourceRoot`	Корневой каталог для исходных файлов проекта.
`projectType`	Одно из "приложение" или "библиотека" Приложение может запускаться самостоятельно в браузере, а библиотека — нет.
`prefix`	Строка, которую Angular добавляет к создаваемым селекторам. Может быть настроена для идентификации приложения или области возможностей.
`schematics`	Набор схем, которые настраивают опции по умолчанию подкоманды `ng generate` для этого проекта. См. раздел Generation schematics
`architect`	Конфигурация по умолчанию для целей конструктора Architect для этого проекта.

Схемы генерации¶

Angular generation schematics — это инструкции по модификации проекта путем добавления файлов или изменения существующих файлов. Отдельные схемы для стандартных подкоманд Angular CLI ng generate собраны в пакете @schematics/angular.

Укажите имя схемы для подкоманды в формате schematic-package:schematic-name; например, схема для генерации компонента — @schematics/angular:component.

JSON-схемы для схем по умолчанию, используемых Angular CLI для создания проектов и частей проектов, собраны в пакете @schematics/angular. Схема описывает опции, доступные Angular CLI для каждой из подкоманд ng generate, как показано в выводе --help.

Поля, указанные в схеме, соответствуют допустимым значениям аргументов и значениям по умолчанию для опций подкоманд Angular CLI. Вы можете обновить файл схемы рабочего пространства, чтобы установить другое значение по умолчанию для опции подкоманды.

Параметры конфигурации инструмента проекта¶

Architect — это инструмент, который используется в Angular CLI для выполнения сложных задач, таких как компиляция и запуск тестов. Architect — это оболочка, которая запускает указанный builder для выполнения заданной задачи в соответствии с конфигурацией target.

Вы можете определить и настроить новые конструкторы и цели для расширения Angular CLI.

Смотрите Angular CLI Builders.

Строители и цели архитекторов по умолчанию¶

Angular определяет конструкторы по умолчанию для использования с определенными командами или с общей командой ng run. JSON-схемы, определяющие опции и значения по умолчанию для каждого из этих дефолтных конструкторов, собраны в пакете @angular-devkit/build-angular.

Схемы определяют опции для следующих конструкторов.

Настройка целей конструктора¶

Раздел architect в файле angular.json содержит набор целей Architect. Многие из целей соответствуют командам Angular CLI, которые их запускают.

Некоторые дополнительные предопределенные цели могут быть запущены с помощью команды ng run, и вы можете определить свои собственные цели.

Каждый объект цели определяет builder для этой цели, который является пакетом npm для инструмента, запускаемого Architect. Каждая цель также имеет раздел options, в котором настраиваются параметры по умолчанию для цели, и раздел configurations, в котором называются и указываются альтернативные конфигурации для цели.

Смотрите пример в Build target ниже.

"architect": {
  "build": {},
  "serve": {},
  "e2e" : {},
  "test": {},
  "lint": {},
  "extract-i18n": {},
  "server": {},
  "app-shell": {}
}

Разделы	Подробности
`architect/build`	Конфигурирует значения по умолчанию для опций команды `ng build`. Дополнительную информацию см. в разделе Build target.
`architect/serve`	Переопределяет параметры сборки по умолчанию и предоставляет дополнительные параметры обслуживания по умолчанию для команды `ng serve`. Помимо опций, доступных для команды `ng build`, добавляются опции, связанные с обслуживанием приложения.
`architect/e2e`	Переопределяет параметры сборки по умолчанию для создания приложений сквозного тестирования с помощью команды `ng e2e`.
`architect/test`	Переопределяет параметры сборки по умолчанию для тестовых сборок и предоставляет дополнительные параметры запуска теста по умолчанию для команды `ng test`.
`architect/lint`	Конфигурирует значения по умолчанию для опций команды `ng lint`, которая выполняет анализ кода исходных файлов проекта.
`architect/extract-i18n`	Настройка параметров по умолчанию для команды `ng extract-i18n`, которая извлекает маркированные строки сообщений из исходного кода и выводит файлы перевода.
`architect/server`	Настройка параметров по умолчанию для создания приложения Universal с рендерингом на стороне сервера с помощью команды `ng run <project>:server`.
`architect/app-shell`	Настраивает параметры по умолчанию для создания оболочки приложения для прогрессивного веб-приложения (PWA) с помощью команды `ng run <project>:app-shell`.

В целом, параметры, для которых можно настроить значения по умолчанию, соответствуют параметрам команд, перечисленным в Angular CLI reference page для каждой команды.

Все опции в конфигурационном файле должны использовать camelCase, а не dash-case.

Цель сборки¶

Раздел architect/build задает значения по умолчанию для опций команды ng build. Он имеет следующие свойства верхнего уровня.

Свойство	Подробности
`builder`	Пакет npm для инструмента сборки, используемого для создания этой цели. По умолчанию для приложения (`ng build myApp`) используется сборщик `@angular-devkit/build-angular:browser`, который использует пакет webpack. NOTE: Для сборки библиотеки (`ng build myLib`) используется другой билдер.
`options`	Этот раздел содержит опции цели сборки по умолчанию, используемые, если не указана альтернативная конфигурация. См. раздел Default build targets.
`configurations`	В этом разделе определяются и называются альтернативные конфигурации для различных целевых назначений. Он содержит раздел для каждой именованной конфигурации, в котором задаются параметры по умолчанию для данного целевого окружения. См. раздел Alternate build configurations.

Альтернативные конфигурации сборки¶

Angular CLI поставляется с двумя конфигурациями сборки: production и development. По умолчанию команда ng build использует конфигурацию production, которая применяет несколько оптимизаций сборки, включая:

Пакетирование файлов
Минимизация лишних пробельных символов
Удаление комментариев и мертвого кода
Переписывание кода для использования коротких, искаженных имен, также известное как минификация.

Вы можете определить и назвать дополнительные альтернативные конфигурации (такие как stage, для instance), соответствующие вашему процессу разработки. Примерами различных конфигураций сборки являются stable, archive и next, используемые самим Angular.io, а также отдельные конфигурации, специфичные для локализации, необходимые для создания локализованных версий приложения.

Подробнее см. в Интернационализация (i18n).

Вы можете выбрать альтернативную конфигурацию, передав ее имя во флаге командной строки --configuration.

Вы также можете передать более одного имени конфигурации в виде списка, разделенного запятыми. Например, чтобы применить конфигурации сборки stage и fr, используйте команду ng build --configuration stage,fr.

В этом случае команда анализирует именованные конфигурации слева направо.

Если несколько конфигураций изменяют одну и ту же настройку, то последнее установленное значение является окончательным.

В данном примере, если обе конфигурации stage и fr задают выходной путь, будет использовано значение в fr.

Дополнительные опции сборки и тестирования¶

Настраиваемые опции для сборки по умолчанию или целевой сборки в целом соответствуют опциям, доступным для команд ng build, ng serve и ng test. Подробнее об этих опциях и их возможных значениях смотрите в Angular CLI Reference.

Некоторые дополнительные опции могут быть установлены только через конфигурационный файл, либо путем прямого редактирования, либо с помощью команды ng config.

Параметры свойств	Детали
`assets`	Объект, содержащий пути к статическим активам для добавления в глобальный контекст проекта. Пути по умолчанию указывают на файл иконок проекта и его каталог `assets`. Подробнее см. в разделе Конфигурация активов.
`styles`	Массив файлов стилей для добавления в глобальный контекст проекта. Angular CLI поддерживает импорт CSS и все основные препроцессоры CSS: sass/scss и less. Подробнее см. в разделе Конфигурация стилей и скриптов.
`stylePreprocessorOptions`	Объект, содержащий пары опций-значений для передачи препроцессорам стилей. Подробнее см. в разделе Конфигурация стилей и скриптов.
`scripts`	Объект, содержащий файлы сценариев JavaScript для добавления в глобальный контекст проекта. Скрипты загружаются точно так же, как если бы вы добавили их в тег `<script>` внутри `index.html`. Подробнее см. в разделе Конфигурация стилей и скриптов.
`budgets`	Тип и пороговые значения бюджета по умолчанию для всего или части вашего приложения. Можно настроить построитель так, чтобы он выдавал предупреждение или ошибку при достижении или превышении порогового размера. См. раздел Configure size budgets. (Недоступно в секции `test`).
`fileReplacements`	Объект, содержащий файлы и их замены во время компиляции. Подробнее см. в разделе Configure target-specific file replacements.
`index`	Настраивает генерацию HTML-индекса приложения. Подробнее см. в разделе Конфигурация индекса. (Доступно только в секции `browser`).

Значения сложной конфигурации¶

Опции assets, index, styles и scripts могут иметь либо простые строковые значения пути, либо объектные значения с определенными полями. Опции sourceMap и optimization могут быть установлены в простое булево значение с командным флагом. Им также можно придать сложное значение с помощью конфигурационного файла.

В следующих разделах более подробно описано, как эти сложные значения используются в каждом конкретном случае.

Конфигурация активов¶

Каждая конфигурация цели build может включать массив assets, в котором перечислены файлы или папки, которые вы хотите скопировать как есть при сборке проекта. По умолчанию копируются директория src/assets/ и src/favicon.ico.

"assets": [
  "src/assets",
  "src/favicon.ico"
]

Чтобы исключить актив, вы можете удалить его из конфигурации активов.

Вы можете дополнительно настроить активы для копирования, указав их как объекты, а не как простые пути относительно корня рабочей области. Объект спецификации актива может иметь следующие поля.

Поля	Подробности
`glob`	A node-glob using `input` as base directory.
`input`	Путь относительно корня рабочей области.
`output`	Путь относительно `outDir` (по умолчанию `dist/project-name`). Из-за проблем с безопасностью, Angular CLI никогда не записывает файлы за пределами пути вывода проекта.
`ignore`	Список глобусов для исключения.
`followSymlinks`	Разрешить шаблонам glob следовать за каталогами симлинков. Это позволяет искать в подкаталогах симлинка. По умолчанию `false`.

Например, пути активов по умолчанию могут быть представлены более подробно с помощью следующих объектов.

"assets": [
  {
    "glob": "**/*",
    "input": "src/assets/",
    "output": "/assets/"
  },
  {
    "glob": "favicon.ico",
    "input": "src/",
    "output": "/"
  }
]

Вы можете использовать эту расширенную конфигурацию для копирования активов извне вашего проекта. Например, следующая конфигурация копирует активы из пакета узла:

"assets": [
  {
    "glob": "**/*",
    "input": "./node_modules/some-package/images",
    "output": "/some-package/"
  }
]

Содержимое node_modules/some-package/images/ будет доступно в dist/some-package/.

В следующем примере поле ignore используется для исключения копирования в сборку определенных файлов из каталога assets:

"assets": [
  {
    "glob": "**/*",
    "input": "src/assets/",
    "ignore": ["**/*.svg"],
    "output": "/assets/"
  }
]

Конфигурация стилей и скриптов¶

Запись массива для опций styles и scripts может быть простой строкой пути или объектом, указывающим на дополнительный файл точки входа. При сборке ассоциированный билдер загружает этот файл и его зависимости как отдельный пакет.

С помощью объекта конфигурации вы можете задать имя пакета для точки входа, используя поле bundleName.

По умолчанию пакет инжектируется, но вы можете установить inject в false, чтобы исключить инжектирование пакета. Например, следующие значения объектов создают и называют пакет, содержащий стили и скрипты, и исключают его из инъекции:

"styles": [
  {
    "input": "src/external-module/styles.scss",
    "inject": false,
    "bundleName": "external-module"
  }
],
"scripts": [
  {
    "input": "src/external-module/main.js",
    "inject": false,
    "bundleName": "external-module"
  }
]

Вы можете смешивать простые и сложные ссылки на файлы для стилей и скриптов.

"styles": [
  "src/styles.css",
  "src/more-styles.css",
  { "input": "src/lazy-style.scss", "inject": false },
  { "input": "src/pre-rename-style.scss", "bundleName": "renamed-style" },
]

Опции препроцессора стилей¶

В Sass вы можете использовать функцию includePaths как для компонентных, так и для глобальных стилей. Это позволяет добавлять дополнительные базовые пути, которые проверяются при импорте.

Чтобы добавить пути, используйте опцию stylePreprocessorOptions:

"stylePreprocessorOptions": {
  "includePaths": [
    "src/style-paths"
  ]
}

Файлы в этом каталоге, такие как src/style-paths/_variables.scss, могут быть импортированы из любой точки вашего проекта без необходимости указания относительного пути:

// src/app/app.component.scss
// A relative path works
@import '../style-paths/variables';
// But now this works as well
@import 'variables';

Также необходимо добавить любые стили или скрипты в конструктор test, если они нужны для модульных тестов. См. также Использование глобальных библиотек времени выполнения внутри приложения.

Конфигурация оптимизации¶

Опция optimization сборщика браузеров может быть как булевым значением, так и объектом для более тонкой настройки. Эта опция включает различные оптимизации вывода сборки, в том числе:

Минификация скриптов и стилей
Смена деревьев
Устранение "мертвого кода
Инкрустация критических CSS
Инкрустация шрифтов

Несколько опций могут быть использованы для тонкой настройки оптимизации приложения.

Опции	Детали	Тип значения	Значение по умолчанию
`scripts`	Включает оптимизацию вывода скриптов.	`boolean`	`true`
`styles`	Включает оптимизацию вывода стилей.	`boolean` \| Опции оптимизации стилей	`true`
`fonts`	Включает оптимизацию для шрифтов. ПРИМЕЧАНИЕ: Для этого требуется доступ в Интернет.	`boolean` \| Опции оптимизации шрифтов	`true`

Параметры оптимизации стилей¶

Параметры	Подробности	Тип значения	Значение по умолчанию
`minify`	Минифицировать определения CSS, удаляя лишние пробелы и комментарии, объединяя идентификаторы и сворачивая значения.	`boolean`	`true`
`inlineCritical`	Извлечение и инлайнирование критических CSS определений для улучшения First Contentful Paint.	`boolean`	`true`

Опции оптимизации шрифтов¶

Опции	Детали	Тип значения	Значение по умолчанию
`inline`	Сокращение запросов на блокировку рендеринга путем инлайнинга внешних CSS-определений Google Fonts и Adobe Fonts в индексный HTML-файл приложения.
ПРИМЕЧАНИЕ: Для этого требуется доступ в Интернет.		`boolean`	`true`

Вы можете задать значение, подобное следующему, чтобы применить оптимизацию к одному или другому параметру:

"optimization": {
  "scripts": true,
  "styles": {
    "minify": true,
    "inlineCritical": true
  },
  "fonts": true
}

Для Universal вы можете уменьшить код, отображаемый в HTML-странице, установив оптимизацию стилей на true.

Конфигурация карты источников¶

Опция sourceMap конструктора браузера может быть либо булевым значением, либо объектом для более тонкой настройки конфигурации для управления исходными картами приложения.

Опции	Детали	Тип значения	Значение по умолчанию
`scripts`	Выводить карты источников для всех скриптов.	`булево`	`истина`
`styles`	Вывод исходных карт для всех стилей.	`boolean`	`true`
`vendor`	Разрешить исходные карты пакетов поставщиков.	`boolean`	`false`
`hidden`	Выводить исходные карты, используемые для инструментов отчетности об ошибках.	`boolean`	`false`

В примере ниже показано, как переключать одно или несколько значений для настройки вывода карт источников:

"sourceMap": {
  "scripts": true,
  "styles": false,
  "hidden": true,
  "vendor": true
}

При использовании скрытых карт источников на карты источников не ссылаются в пакете. Это полезно, если карты источников нужны только для отображения трассировки стека ошибок в инструментах отчетности об ошибках. Скрытые карты источников не отображают ваши карты источников в инструментах разработчика браузера.

Конфигурация индекса¶

Настраивает генерацию HTML-индекса приложения.

Параметр index может быть как строкой, так и объектом для более тонкой настройки.

При передаче значения в виде String для сгенерированного файла будет использовано имя файла по указанному пути, который будет создан в корне настроенного пути вывода приложения.

Параметры индекса¶

Опции	Детали	Тип значения	Значение по умолчанию
`input`	Путь к файлу, который будет использоваться для генерируемого приложением HTML-индекса.	`string`
`output`	Путь к выходному файлу HTML-индекса приложения. Будет использован полный путь и будет считаться относительным к настроенному пути вывода приложения.	`string`	`index.html`

Ссылки¶

Angular workspace configuration

Конфигурация рабочего пространства Angular¶

Общая структура JSON¶

Параметры конфигурации Angular CLI¶

Опции кэша¶

Параметры предупреждений¶

Параметры конфигурации проекта¶

Схемы генерации¶

Параметры конфигурации инструмента проекта¶

Строители и цели архитекторов по умолчанию¶

Настройка целей конструктора¶

Цель сборки¶

Альтернативные конфигурации сборки¶

Дополнительные опции сборки и тестирования¶

Значения сложной конфигурации¶

Конфигурация активов¶

Конфигурация стилей и скриптов¶

Опции препроцессора стилей¶

Конфигурация оптимизации¶

Параметры оптимизации стилей¶

Опции оптимизации шрифтов¶

Конфигурация карты источников¶

Конфигурация индекса¶

Параметры индекса¶

Ссылки¶

Комментарии