Установка и настройка Astro

Команда create astro — это самый быстрый способ начать новый проект Astro с нуля. Он проведёт вас через все этапы настройки вашего нового проекта Astro и позволит выбрать один из нескольких официальных шаблонов.

Или вы можете начать свой проект используя любую существующую тему или стартовый шаблон.

Чтобы установить Astro вручную, обратитесь к нашему пошаговому руководству по установке вручную.

Требования

Node.js - v18.17.1, v20.3.0 или выше. ( v19 не поддерживается.)
Текстовый редактор - Мы рекомендуем VS Code с нашим официальным расширением Astro.
Терминал - Доступ к Astro осуществляется через интерфейс командной строки (CLI).

Совместимость с браузерами

Astro создан на основе Vite, который по умолчанию нацелен на браузеры с современной поддержкой JavaScript. Для получения полной информации вы можете посмотреть список поддерживаемых версий браузеров в Vite.

Создание нового проекта

Установка с помощью интерфейса командной строки

Выполните следующую команду в терминале, чтобы запустить наш удобный мастер установки:
- npm
- pnpm
- yarn
Окно терминала
# создать новый проект с помощью npm npm create astro@latest
Окно терминала
# создать новый проект с помощью pnpm pnpm create astro@latest
Окно терминала
# создать новый проект с помощью yarn yarn create astro
Вы можете запустить create astro в любом месте на вашем компьютере, поэтому нет необходимости создавать новый пустой каталог для вашего проекта перед началом работы. Если у вас ещё нет пустого каталога для нового проекта, мастер поможет создать его автоматически.

Если всё прошло успешно, вы увидите сообщение об успехе, за которым последуют рекомендации по дальнейшим действиям. Теперь, когда ваш проект создан, вы можете выполнить команду cd в новом каталоге проекта, чтобы начать использовать Astro.
Если вы пропустили шаг “Install dependencies?” во время работы мастера установки, то обязательно установите свои зависимости, прежде чем продолжить.
Теперь можно запустить сервер разработки Astro и увидеть живое превью вашего проекта во время сборки!

Использование темы или стартового шаблона

Вы также можете начать новый проект Astro на основе официального примера или ветки main любого репозитория GitHub, передав аргумент --template команде create astro.

Ознакомьтесь с нашей витриной тем и стартовых шаблонов, где представлены темы для блогов, портфолио, сайтов документации, целевых страниц и многого другого! Или воспользуйтесь поиском на GitHub, где можно найти ещё больше стартовых проектов.

Выполните следующую команду в терминале, подставив официальное название стартового шаблона Astro или имя пользователя и репозиторий GitHub темы, которую вы хотите использовать:

# создать новый проект с официальным примером
npm create astro@latest -- --template <example-name>

# создать новый проект на основе главной ветки репозитория GitHub
npm create astro@latest -- --template <github-username>/<github-repo>

# создать новый проект с официальным примером
pnpm create astro@latest --template <example-name>

# создать новый проект на основе главной ветки репозитория GitHub
pnpm create astro@latest --template <github-username>/<github-repo>

# создать новый проект с официальным примером
yarn create astro --template <example-name>

# создать новый проект на основе главной ветки репозитория GitHub
yarn create astro --template <github-username>/<github-repo>

По умолчанию эта команда будет использовать ветку main хранилища шаблонов. Чтобы использовать другое имя ветки, передайте его в качестве части аргумента --template: <github-username>/<github-repo>#<branch>.

Ответьте на вопросы и следуйте инструкциям мастера установки.
Теперь можно запустить сервер разработки Astro и увидеть живое превью вашего проекта во время сборки!

Редактирование вашего проекта

Чтобы внести изменения в проект, откройте папку проекта в редакторе кода. Работа в режиме разработки с запущенным dev-сервером позволяет вам видеть обновления на сайте по мере редактирования кода.

Вы также можете настроить некоторые аспекты вашей среды разработки, например, настроить TypeScript или установить официальные расширения редактора Astro.

Запуск сервера разработки Astro

Astro поставляется со встроенным сервером разработки, в котором есть всё необходимое для создания проекта. Команда astro dev в терминале запустит локальный сервер разработки, и вы сможете увидеть свой новый сайт в действии.

Каждый стартовый шаблон поставляется с предварительно настроенным скриптом, который будет запускать astro dev для вас. Перейдя в каталог проекта, используйте ваш любимый менеджер пакетов, чтобы выполнить эту команду и запустить сервер разработки Astro.

npm run dev

pnpm run dev

yarn run dev

Если всё пройдет успешно, Astro теперь будет обслуживать ваш проект по адресу http://localhost:4321/. Перейдите по этой ссылке в браузере и посмотрите на свой новый сайт!

Работа в режиме разработки

Astro будет отслеживать изменения файлов в каталоге src/ и обновлять предварительный просмотр сайта по мере сборки, поэтому вам не придётся перезапускать сервер при внесении изменений во время разработки. При работе dev-сервера вы всегда сможете увидеть в браузере актуальную версию вашего сайта.

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

Если после запуска dev-сервера вы не можете открыть свой проект в браузере, вернитесь в терминал, где вы выполняли команду dev, и проверьте отображаемые сообщения. Так вы поймёте, произошла ли ошибка или обслуживается ли ваш проект по URL-адресу, отличному от http://localhost:4321/.

Настройка среды разработки

Изучите приведённые ниже руководства, чтобы улучшить свой опыт разработки.

Настройка редактора Настройте редактор кода, чтобы улучшить свою работу и открыть новые возможности.

Панель разработчика Изучите полезные функции панели инструментов разработчика.

TypeScript в Astro

Astro поставляется со встроенной поддержкой TypeScript, которая может помочь предотвратить ошибки во время выполнения, определяя формы объектов и компонентов в вашем коде.

Вам не нужно писать код на TypeScript в своих проектах Astro, чтобы воспользоваться его преимуществами. Astro всегда воспринимает код компонентов как TypeScript, а расширение Astro для VSCode будет делать выводы, чтобы обеспечить автозавершение, подсказки и ошибки в вашем редакторе.

Подробнее об использовании и настройке TypeScript в Astro

Сборка и предварительный просмотр вашего сайта

Чтобы проверить версию вашего сайта, которая будет создана во время сборки, закройте сервер разработки (Ctrl + C) и запустите соответствующую команду сборки для вашего менеджера пакетов в терминале:

npm run build

pnpm build

yarn run build

Astro создаст готовую к развёртыванию версию вашего сайта в отдельной папке (по умолчанию dist/), и вы сможете наблюдать за её развитием в терминале. Это предупредит вас о любых ошибках сборки проекта до его развёртывания в производство. Если TypeScript настроен на strict или strictest, сценарий build также проверит ваш проект на наличие ошибок типа.

Когда сборка будет завершена, запустите соответствующую команду preview (например, npm run preview) в терминале, и вы сможете просмотреть собранную версию сайта локально в том же окне предварительного просмотра браузера.

Обратите внимание, что в этом случае ваш код просматривается в том виде, в котором он существовал на момент последнего запуска команды сборки. Это позволит вам увидеть, как будет выглядеть ваш сайт, когда он будет развёрнут в Интернете. Любые последующие изменения, внесённые в код после сборки, не будут отражены во время предварительного просмотра сайта, пока вы не выполните команду сборки снова.

Используйте комбинацию Ctrl + C, чтобы выйти из предварительного просмотра и запустить другую команду терминала, например, перезапустить сервер разработки, чтобы вернуться в работу в режиме разработки, который обновляется по мере редактирования и отображает предварительный просмотр изменений вашего кода.

Узнайте больше об интерфейсе командной строки Astro и командах терминала, которые вы будете использовать при сборке с помощью Astro.

Развёртывание вашего нового сайта

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

Следующие шаги

Отлично! Теперь вы готовы начать строительство с помощью Astro! 🥳

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

Изучите возможности Astro

Понимание кодовой базы Узнайте о структуре файлов Astro в нашем руководстве по структуре проекта.

Создание коллекций контента Добавляйте контент на новый сайт с проверкой внешнего вида и автоматической защитой типов.

Добавление анимации переходов Создайте плавные переходы между страницами и анимацию.

Знакомство с островами Прочитайте об островной архитектуре Astro.

Пройдите вводный инструктаж

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

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

Ручная установка

В этом руководстве вы узнаете, как вручную установить и настроить новый проект Astro.

Если вы не хотите использовать наш автоматический CLI-инструмент create astro, вы можете создать проект самостоятельно, следуя руководству ниже.

Создайте директорию

Создайте пустой каталог с именем вашего проекта, а затем перейдите в него.
Окно терминала
```
mkdir my-astro-project
cd my-astro-project
```
Как только вы окажетесь в новой директории, создайте файл проекта package.json. Так вы будете управлять зависимостями проекта, включая Astro. Если вы не знакомы с этим форматом, выполните следующую команду, чтобы создать такой файл.
- npm
- pnpm
- yarn
Окно терминала
npm init --yes
Окно терминала
pnpm init
Окно терминала
yarn init --yes
Установите Astro

Сначала установите зависимости Astro в свой проект.

Astro должен быть установлен локально, а не глобально. Убедитесь, что вы не запускаете npm install -g astro, pnpm add -g astro или yarn add global astro.
- npm
- pnpm
- yarn
Окно терминала
npm install astro
Окно терминала
pnpm add astro
Окно терминала
yarn add astro
Затем замените всю секцию «scripts» в package.json следующими данными:
package.json
```
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```
Вы будете использовать эти скрипты далее в руководстве для запуска Astro и выполнения различных команд.

Создайте свою первую страницу

В текстовом редакторе создайте новый файл в вашей директории по адресу src/pages/index.astro. Это будет ваша первая страница в проекте.

Скопируйте и вставьте следующий фрагмент кода (включая символы ---) в ваш новый файл:

---
// Добро пожаловать в Astro! Всё, что находится между символами «---» — это
// «метаданные компонента». Они никогда не отображаются в браузере.
console.log('Это запускается в терминале, а не в браузере!');
---
<!-- Ниже приведён «шаблон компонента». Это просто HTML, но с
    небольшой магией, чтобы помочь вам создавать великолепные шаблоны. -->
<html>
  <body>
    <h1>Привет, мир!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

Создайте свой первый статический ресурс

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

В текстовом редакторе создайте новый файл в вашей директории по адресу public/robots.txt. robots.txt — это простой файл, который большинство сайтов включают в себя, чтобы указать поисковым ботам, таким как Google, как обращаться с вашим сайтом.

Скопируйте и вставьте следующий фрагмент кода в новый файл:
public/robots.txt
```
# Пример: Разрешить всем ботам сканировать и индексировать ваш сайт.
# Полный синтаксис: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```
Создайте файл astro.config.mjs

Astro настраивается с помощью файла astro.config.mjs. Этот файл необязателен, если вам не нужно настраивать Astro, но вы можете захотеть создать его сейчас.

Создайте astro.config.mjs в корне вашего проекта и скопируйте в него приведённый ниже код:
astro.config.mjs
```
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```
Если вы хотите включить компоненты фреймворка пользовательского интерфейса, такие как React, Svelte и др. Если вы используете в своем проекте другие инструменты, такие как Tailwind или Partytown, здесь вы сможете вручную импортировать и настроить нужные интеграции.

Для получения дополнительной информации читайте справочник по конфигурации API.
Добавьте поддержку TypeScript

TypeScript настраивается с помощью файла tsconfig.json. Даже если вы не пишете код на TypeScript, этот файл важен для того, чтобы такие инструменты, как Astro и VS Code, знали, как понимать ваш проект. Некоторые функции (например, импорт пакетов npm) не полностью поддерживаются в редакторе без файла tsconfig.json.

Если вы собираетесь писать код на TypeScript, рекомендуется использовать шаблон Astro strict или strictest. Посмотреть и сравнить три конфигурации шаблонов можно на сайте astro/tsconfigs/.

Создайте файл tsconfig.json в корне проекта и скопируйте в него приведённый ниже код. (Вы можете использовать base, strict или strictest для своего шаблона TypeScript):
tsconfig.json
```
{
  "extends": "astro/tsconfigs/base"
}
```
Подробнее об этом читайте в руководстве по настройке TypeScript.
Следующие шаги

Если вы выполнили все шаги, описанные выше, каталог вашего проекта должен выглядеть следующим образом:
- Директорияnode_modules/
  - …
- Директорияpublic/
  - robots.txt
- Директорияsrc/
  - Директорияpages/
    index.astro
- astro.config.mjs
- package-lock.json, или yarn.lock, pnpm-lock.yaml и т. д.
- package.json
- tsconfig.json
Теперь можно запустить сервер разработки Astro и увидеть живое превью вашего проекта во время сборки!

Внести свой вклад

Сообщество