Команды CLI

Вы можете использовать интерфейс командной строки (CLI), предоставляемый Astro, для разработки, сборки и предварительного просмотра вашего проекта из окна терминала.

Команды `astro`

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

Одна из команд, которую вы будете использовать чаще всего, — astro dev. Эта команда запускает сервер разработки и предоставляет вам живой, обновляемый предварительный просмотр вашего сайта в браузере во время работы:

# запуск сервера разработки
npx astro dev

# запуск сервера разработки
pnpm astro dev

# запуск сервера разработки
yarn astro dev

Вы можете набрать в терминале astro --help, чтобы вывести список всех доступных команд:

npx astro --help

pnpm astro --help

yarn astro --help

На экране вашего терминала появится следующее сообщение:

astro [command] [...flags]

Commands
              add  Add an integration.
            build  Build your project and write it to disk.
            check  Check your project for errors.
              dev  Start the development server.
             docs  Open documentation in your web browser.
             info  List info about your current Astro setup.
          preview  Preview your build locally.
             sync  Generate content collection types.
      preferences  Configure user preferences.
        telemetry  Configure telemetry settings.

Global Flags
  --config <path>  Specify your config file.
    --root <path>  Specify your project root folder.
     --site <url>  Specify your project site.
--base <pathname>  Specify your project base.
        --verbose  Enable verbose logging.
         --silent  Disable all logging.
        --version  Show the version number and exit.
           --open  Open the app in the browser on server start.
           --help  Show this help message.

Скрипты `package.json`

Вы также можете использовать скрипты в package.json для более коротких версий этих команд. Использование скриптов позволяет вам использовать те же команды, с которыми вы можете быть знакомы по другим проектам, например npm run build.

Следующие скрипты для наиболее распространённых команд astro (astro dev, astro build и astro preview) добавляются автоматически при создании проекта с помощью инструмента create astro.

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

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

Часто вы будете использовать эти команды astro или скрипты, которые их запускают, без каких-либо флагов. Добавляйте флаги к команде, когда хотите настроить её поведение. Например, вы можете запустить сервер разработки на другом порту или создать сайт с подробными логами для отладки.

# запуск сервера разработки на порту 8080, используя скрипт `start` в файле `package.json`.
npm run start -- --port 8080

# сборка вашего сайта с подробными логами, используя скрипт `build` в файле `package.json`
npm run build -- --verbose

# запуск сервера разработки на порту 8080, используя скрипт `start` в файле `package.json`
pnpm start --port 8080

# сборка вашего сайта с подробными логами, используя скрипт `build` в файле `package.json`
pnpm build --verbose

# запуск сервера разработки на порту 8080, используя скрипт `start` в файле `package.json`
yarn start --port 8080

# сборка вашего сайта с подробными логами, используя скрипт `build` в файле `package.json`
yarn build --verbose

`astro dev`

Запускает сервер разработки Astro. Это локальный HTTP-сервер, который не объединяет ресурсы. Он использует горячую замену модулей (HMR) для обновления браузера при сохранении изменений в редакторе.

`astro build`

Создает ваш сайт для развёртывания. По умолчанию генерируются статические файлы и помещаются в каталог dist/. Если SSR включен, будут сгенерированы необходимые серверные файлы для обслуживания вашего сайта.

Может сочетаться с общими флагами, описанными ниже.

`astro preview`

Запускает локальный сервер для обслуживания содержимого вашего статического каталога (по умолчанию dist/), созданного при запуске astro build.

Эта команда позволяет локально просмотреть сайт после сборки, чтобы выявить любые ошибки в результатах сборки перед её развёртыванием. Она не предназначена для запуска в производстве. Чтобы получить помощь в развёртывании сайта на производстве, ознакомьтесь с нашим руководством Развёртывание сайта Astro.

Начиная с версии Astro 1.5.0, astro preview также работает для сборок SSR, если вы используете адаптер, который поддерживает эту функцию. В настоящее время только адаптер Node поддерживает astro preview.

Может сочетаться с общими флагами, описанными ниже.

`astro check`

Выполняет диагностику (например, проверку типов в файлах .astro) вашего проекта и сообщает об ошибках в консоль. Если обнаружены ошибки, процесс завершится с кодом 1.

Эта команда предназначена для использования в рабочих процессах CI.

Флаги

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

`--watch`

Команда будет следить за изменениями в вашем проекте и сообщать о любых ошибках.

Подробнее о проверке типов в Astro.

`astro sync`

Добавлено в: astro@2.0.0

Генерирует типы TypeScript для всех модулей Astro. Это настраивает src/env.d.ts файл для определения типов и определяет модули для функций, которые зависят от сгенерированных типов:

Модуль astro:content для API коллекций контента.
Модуль astro:db для Astro DB.

`astro add`

Добавляет интеграцию в вашу конфигурацию. Подробнее в руководстве по интеграциям.

`astro docs`

Запускает веб-сайт Astro Docs прямо из терминала.

`astro info`

Сообщает полезную информацию о текущем окружении Astro. Полезно для предоставления информации при открытии проблемы.

astro info

Пример вывода:

Astro                    v3.0.12
Node                     v20.5.1
System                   macOS (arm64)
Package Manager          pnpm
Output                   server
Adapter                  @astrojs/vercel/serverless
Integrations             none

`astro preferences`

Управляйте предпочтениями пользователей с помощью команды astro preferences. Пользовательские предпочтения являются специфическими для отдельных пользователей Astro, в отличие от файла astro.config.mjs, который изменяет поведение всех, кто работает над проектом.

Пользовательские настройки по умолчанию привязаны к текущему проекту и хранятся в локальном файле .astro/settings.json.

Используя флаг --global, пользовательские настройки можно также применить ко всем проектам Astro на текущей машине. Глобальные пользовательские настройки хранятся в специфическом для операционной системы месте.

Например, чтобы отключить панель devToolbar в конкретном проекте Astro:

astro preferences disable devToolbar

Чтобы отключить панель devToolbar во всех проектах Astro на текущей машине:

astro preferences disable --global devToolbar

Впоследствии панель devToolbar можно включить с помощью:

astro preferences enable devToolbar

Команда reset возвращает предпочтение к значению по умолчанию:

astro preferences reset devToolbar

Команда list выводит текущие настройки всех конфигурируемых пользовательских предпочтений. Она также поддерживает машиночитаемый вывод --json.

astro preferences list

`astro telemetry`

Устанавливает конфигурацию телеметрии для текущего пользователя CLI. Телеметрия — это анонимные данные, которые дают команде Astro представление о том, какие функции Astro используются чаще всего. Дополнительные сведения см. на странице Телеметрия Astro.

Телеметрию можно отключить с помощью этой команды CLI:

astro telemetry disable

Впоследствии телеметрию можно снова включить с помощью:

astro telemetry enable

Команда reset сбрасывает данные телеметрии:

astro telemetry reset

Общие флаги

`--root <path>`

Указывает путь к корню проекта. Если путь не указан, корнем считается текущий рабочий каталог.

Корень используется для поиска файла конфигурации Astro.

astro --root myRootFolder/myProjectFolder dev

`--config <path>`

Указывает путь к файлу конфигурации относительно корня проекта. По умолчанию astro.config.mjs. Используйте это значение, если вы используете другое имя для файла конфигурации или файл конфигурации находится в другой папке.

astro --config config/astro.config.mjs dev

`--outDir <path>`

Добавлено в: astro@3.3.0

Настраивает outDir для вашего проекта. Передача этого флага отменяет значение outDir в вашем файле astro.config.mjs, если оно существует.

`--site <url>`

Настраивает site для вашего проекта. Передача этого флага отменяет значение site в вашем файле astro.config.mjs, если оно существует.

`--base <pathname>`

Добавлено в: astro@1.4.1

Настраивает base для вашего проекта. Передача этого флага отменяет значение base в вашем файле astro.config.mjs, если оно существует.

`--port <number>`

Указывает, на каком порту запускать dev-сервер и сервер предварительного просмотра. По умолчанию 4321.

`--host [optional host address]`

Устанавливает, какие сетевые IP-адреса должны прослушивать сервер разработки и сервер предпросмотра (т. е. IP-адреса, не относящиеся к localhost). Это может быть полезно для тестирования проекта на локальных устройствах, таких как мобильный телефон, во время разработки.

--host — прослушивать все адреса, включая адреса локальной сети и публичные адреса
--host <custom-address> — выставлять IP-адрес сети по адресу <custom-address>

`--verbose`

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

`--silent`

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

Глобальные флаги

Используйте эти флаги, чтобы получить информацию о CLI astro.

`--version`

Выводит номер версии Astro и выходит из программы.

`--open`

Автоматически открывает приложение в браузере при запуске сервера. Можно передать полную строку URL (например, --open http://example.com) или имя пути (например, --open /about), чтобы указать URL для открытия.

`--help`

Выводит сообщение о помощи и завершает работу.

Расширенные API (экспериментальные)

Если вам нужно больше контроля при запуске Astro, пакет "astro" также экспортирует API для программного запуска команд CLI.

Эти API являются экспериментальными, и сигнатура их API может измениться. Любые обновления будут упомянуты в списке изменений Astro, а информация ниже всегда будет отображать текущую, актуальную информацию.

`AstroInlineConfig`

Тип AstroInlineConfig используется всеми командными API, представленными ниже. Он расширяет пользовательский тип конфигурации Astro.:

interface AstroInlineConfig extends AstroUserConfig {
  configFile?: string | false;
  mode?: "development" | "production";
  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

`configFile`

Тип: string | false
По умолчанию: undefined

Пользовательский путь к файлу конфигурации Astro.

Если это значение не определено (по умолчанию) или не установлено, Astro будет искать файл astro.config.(js,mjs,ts) относительно root и загружать его, если найдет.

Если задан относительный путь, он будет разрешен на основе текущего рабочего каталога.

Установите значение false, чтобы отключить загрузку любых файлов конфигурации.

Встроенный конфиг, переданный в этот объект, будет иметь наивысший приоритет при объединении с загруженным пользовательским конфигом.

`mode`

Тип: "development" | "production"
По умолчанию: "development" при запуске astro dev, "production" при запуске astro build

Режим, используемый при сборке вашего сайта для генерации кода либо “development” (разработка), либо “production” (производство).

`logLevel`

Тип: "debug" | "info" | "warn" | "error" | "silent"
По умолчанию: "info"

Уровень регистрации для фильтрации сообщений, регистрируемых Astro.

"debug": Записывайте в журнал все, включая шумную отладочную диагностику.
"info": Записывать в журнал информационные сообщения, предупреждения и ошибки.
"warn": Заносить в журнал предупреждения и ошибки.
"error": Заносить в журнал только ошибки.
"silent": Не вести журнал.

`dev()`

Тип: (inlineConfig: AstroInlineConfig) => AstroDevServer.

Подобно astro dev, он запускает сервер разработки Astro.

import { dev } from "astro";

const devServer = await dev({
  root: "./my-project",
});

// При необходимости остановите сервер
await devServer.stop();

`build()`

Тип: (inlineConfig: AstroInlineConfig) => void.

Подобно astro build, он создает ваш сайт для развертывания.

import { build } from "astro";

await build({
  root: "./my-project",
});

`preview()`

Тип: (inlineConfig: AstroInlineConfig) => AstroPreviewServer.

Аналогично astro preview, запускает локальный сервер для обслуживания вашего статического каталога dist/.

import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// При необходимости остановите сервер
await previewServer.stop();

`sync()`

Тип: (inlineConfig: AstroInlineConfig) => number

Подобно astro sync, он генерирует типы TypeScript для всех модулей Astro

import { sync } from "astro";

const exitCode = await sync({
  root: "./my-project",
});

process.exit(exitCode)

Astro Studio CLI

`astro login`

Аутентификация с помощью Astro Studio. Это необходимо для выполнения всех команд управления базой данных, включая astro link.

`astro link`

Ссылка на вашу базу данных, размещённую в Studio. Это необходимо для выполнения команд Astro DB для управления базой данных. Для привязки базы данных вам будет предложено выбрать существующую базу данных или создать новую.

`astro logout`

Выход из Astro Studio и удаление всех локально сохранённых ключей аутентификации.

Команды CLI

Команды astro

Скрипты package.json

astro dev

astro build

astro preview

astro check

Флаги

--watch

astro sync

astro add

astro docs

astro info

astro preferences

astro telemetry

Общие флаги

--root <path>

--config <path>

--outDir <path>

--site <url>

--base <pathname>

--port <number>

--host [optional host address]

--verbose

--silent