Обновление до Astro v3
Это руководство поможет вам перейти с Astro v2 на Astro v3.
Вам нужно обновить старый проект до v2? Смотрите наше руководство по миграции старых проектов.
Обновление Astro
Заголовок раздела Обновление AstroОбновите версию Astro для вашего проекта до последней версии с помощью менеджера пакетов. Если вы используете интеграции Astro, также обновите их до последней версии.
После обновления Astro до последней версии вам может не потребоваться вносить какие-либо изменения в ваш проект!
Но если вы заметите ошибки или неожиданное поведение, пожалуйста, проверьте, что изменилось и что может потребовать обновления в вашем проекте.
Удаление экспериментальных флагов Astro v3.0
Заголовок раздела Удаление экспериментальных флагов Astro v3.0Удалите следующие экспериментальные флаги из astro.config.mjs
:
Эти функции теперь доступны по умолчанию:
- Анимации Переходов для анимированных переходов между страницами и постоянных островов.
- Новый API сервисов изображений
astro:assets
для использования изображений в Astro, включая новый компонент<Image />
и функциюgetImage()
.
Подробнее об этих двух интересных функциях и многом другом читайте в посте блога 3.0!
Изменения в Astro v3.0
Заголовок раздела Изменения в Astro v3.0Astro v3.0 включает в себя некоторые изменения, а также удаление некоторых ранее устаревших функций. Если после обновления до версии 3.0 ваш проект работает не так, как ожидалось, ознакомьтесь с этим руководством, в котором вы найдете обзор всех изменений и инструкции по обновлению вашей кодовой базы.
Полную информацию о выпуске смотрите в журнале изменений.
Удалено: Поддержка Node 16
Заголовок раздела Удалено: Поддержка Node 16Срок службы Node 16 истекает в сентябре 2023 года.
Astro v3.0 полностью отказывается от поддержки Node 16, чтобы все пользователи Astro могли воспользоваться более современными возможностями Node.
Что делать?
Заголовок раздела Что делать?Убедитесь, что в вашей среде разработки и среде развертывания используется Node 18.14.1
или выше.
-
Проверьте локальную версию Node, используя:
-
Проверьте собственную документацию среды развертывания, чтобы убедиться, что она поддерживает Node 18.
Вы можете указать Node
18.14.1
для вашего проекта Astro либо в настройках конфигурации панели управления, либо в файле.nvmrc
.
Удалено: Поддержка TypeScript 4
Заголовок раздела Удалено: Поддержка TypeScript 4В Astro v2.x предустановки tsconfig.json
включают поддержку TypeScript 4.x и 5.x.
В Astro v3.0 предустановки tsconfig.json
обновлены и поддерживают только TypeScript 5.x. Теперь Astro предполагает, что вы используете TypeScript 5.0 (март 2023 года), или что ваш редактор включает его (например, VS Code 1.77).
Что мне делать?
Заголовок раздела Что мне делать?Если вы установили TypeScript локально, обновите его по крайней мере до версии 5.0.
Удалено: @astrojs/image
Заголовок раздела Удалено: @astrojs/imageВ Astro v2.x предлагалась официальная интеграция с изображениями, которая включала компоненты Astro <Image />
и <Picture />
.
В Astro v3.0 эта интеграция полностью удалена из кодовой базы. Новое решение Astro для изображений - встроенный API сервисов изображений: astro:assets
.
Что делать?
Заголовок раздела Что делать?Удалите интеграцию @astrojs/image
из вашего проекта. Вам нужно будет не только удалить интеграцию, но и обновить или удалить все операторы импорта и существующие компоненты <Image />
и <Picture />
. Также может потребоваться настройка предпочтительной службы обработки изображений по умолчанию.
Переход на astro:assets
также принесет некоторые новые опции и возможности работы с изображениями, которые вы, возможно, захотите использовать.
Удалено: компонент <Markdown />
Заголовок раздела Удалено: компонент <Markdown />В версии Astro v1.x компонент <Markdown />
был устаревшим и перенесен во внешний пакет.
В Astro v3.0 полностью удален пакет @astrojs/markdown-component
. Компонент Astro <Markdown />
больше не будет работать в вашем проекте.
Что делать?
Заголовок раздела Что делать?Удалите все экземпляры пакета @astrojs/markdown-component
.
Чтобы продолжить использовать подобный <Markdown />
компонент в своем коде, рассмотрите возможность использования интеграций сообщества, например astro-remote
. Обязательно обновите импорт и атрибуты компонента <Markdown />
, если это необходимо, в соответствии с документацией по интеграции.
В противном случае удалите все ссылки на импорт компонента Astro <Markdown />
и сам компонент в файлах .astro
. Вам нужно будет переписать содержимое в HTML напрямую или импортировать Markdown из файла .md
.
Удалено: устаревшие API версии 1.x
Заголовок раздела Удалено: устаревшие API версии 1.xВ версии 1.x Astro отказалась от первоначальных настроек конфигурации, а также от поддержки <style global>
и <script hoist>
. Однако они все еще поддерживались для обратной совместимости.
В Astro v3.0 эти устаревшие API полностью удалены. Вместо них следует использовать официально поддерживаемые настройки конфигурации (EN) и современные синтаксисы <style is:global>
и <script>
.
Что мне делать?
Заголовок раздела Что мне делать?Если вы продолжаете использовать API версии 1.x, используйте новые API для каждой функции:
- Утратившие актуальность настройки конфигурации: См. руководство по миграции 0.26 (EN)
- Утратившие актуальность типы атрибутов скриптов/стилей: См. руководство по миграции 0.26 (EN)
Удалено: Частичные шиммы для веб-интерфейсов в коде сервера
Заголовок раздела Удалено: Частичные шиммы для веб-интерфейсов в коде сервераВ Astro v2.x Astro предоставлял частичные шиммы для веб-интерфейсов, таких как document
или localStorage
, в серверном коде. Эти шиммы часто были неполными и ненадежными.
В Astro v3.0 эти частичные шиммы полностью удалены. Веб-интерфейсы больше не доступны в рендеренном коде.
Что делать?
Заголовок раздела Что делать?Если вы используете веб-интерфейсы в рендеренных компонентах, вам нужно либо сделать их использование условным, либо использовать клиентскую директиву client:only
(EN).
Удалено: image
из astro:content
в схеме коллекций контента
Заголовок раздела Удалено: image из astro:content в схеме коллекций контентаВ Astro v2.x API коллекций контента устарел экспорт image
из astro:content
для использования в схемах коллекций контента.
В Astro v3.0 этот экспорт полностью удален.
Что мне делать?
Заголовок раздела Что мне делать?Если вы используете устаревший экспорт image()
из astro:content
, удалите его, так как он больше не существует. Вместо этого проверяйте изображения через помощник image
из schema
:
Удалено: названия тем Shiki до версии 0.14
Заголовок раздела Удалено: названия тем Shiki до версии 0.14В Astro v2.x некоторые названия тем Shiki были переименованы, но оригинальные названия были сохранены для обратной совместимости.
В Astro v3.0 оригинальные названия удалены в пользу переименованных.
Что делать?
Заголовок раздела Что делать?Если в вашем проекте используется какая-либо из перечисленных ниже тем, переименуйте ее в обновленное название:
material-darker
->material-theme-darker
material-default
->material-theme
material-lighter
->material-theme-lighter
material-ocean
->material-theme-ocean
material-palenight
->material-theme-palenight
Удалено: class:list
функции
Заголовок раздела Удалено: class:list функцииВ Astro v2.x директива class:list
(EN) использовала собственную реализацию, вдохновленную clsx
с несколькими дополнительными функциями, такими как дедупликация и поддержка Set
.
Astro v3.0 теперь использует clsx
непосредственно для class:list
, который не поддерживает дедупликацию или значения Set
.
Что делать?
Заголовок раздела Что делать?Замените все элементы Set
, переданные в директиву class:list
, на обычный Array
.
Устранено: передача class:list
в качестве свойства
Заголовок раздела Устранено: передача class:list в качестве свойстваВ Astro v2.x значения class:list
(EN) передавались компонентам через Astro.props['class:list']
.
Astro v3.0 нормализует значения class:list
в строку перед отправкой в компоненты через Astro.props['class']
.
Что делать?
Заголовок раздела Что делать?Удалите весь код, который ожидает получить свойство class:list
.
Убрано: преобразование kebab-case в camelCase для CSS переменных
Заголовок раздела Убрано: преобразование kebab-case в camelCase для CSS переменныхВ Astro v2.x camelCase CSS-переменные (EN), переданные в атрибут style
, отображались как в camelCase (как написано), так и в kebab-case (сохранено для обратной совместимости).
Astro v3.0 удаляет преобразование kebab-case для этих имен CSS-переменных в camelCase, и теперь отображается только оригинальная CSS-переменная в camelCase.
Что мне делать?
Заголовок раздела Что мне делать?Если вы полагались на то, что Astro преобразует кебаб-кейс в ваших стилях, обновите существующие стили до camelCase, чтобы не пропустить стили. Например:
Устранено: автоматическое выравнивание возвращаемого значения функции getStaticPaths()
.
Заголовок раздела Устранено: автоматическое выравнивание возвращаемого значения функции getStaticPaths().В Astro v2.x возвращаемое значение функции getStaticPaths()
автоматически выравнивалось, чтобы вы могли вернуть массив массивов без ошибок.
В Astro v3.0 автоматическое выравнивание результата getStaticPaths()
удалено.
Что делать?
Заголовок раздела Что делать?Если вы возвращаете массив массивов вместо массива объектов (как и ожидалось), то теперь следует использовать .flatMap
и .flat
, чтобы убедиться, что вы возвращаете плоский массив.
Если вам необходимо обновить код, будет выдано сообщение об ошибке, указывающее, что возвращаемое значение getStaticPath()
должно быть массивом объектов.
Перемещено: astro check
теперь требует внешнего пакета
Заголовок раздела Перемещено: astro check теперь требует внешнего пакетаВ Astro v2.x пакет astro check
был включен в Astro по умолчанию, а его зависимости были собраны в Astro. Это означало, что пакет был больше, независимо от того, использовали вы astro check
или нет. Это также не позволяло вам контролировать версию TypeScript и языкового сервера Astro.
В Astro v3.0 команда astro check
перенесена из ядра Astro и теперь требует внешнего пакета @astrojs/check
. Кроме того, для использования команды astro check
в проекте необходимо установить typescript
.
Что делать?
Заголовок раздела Что делать?Запустите команду astro check
после обновления до Astro v3.0 и следуйте подсказкам для установки необходимых зависимостей, либо вручную установите @astrojs/check
и typescript
в ваш проект.
Утратило актуальность: build.excludeMiddleware
и build.split
.
Заголовок раздела Утратило актуальность: build.excludeMiddleware и build.split.В Astro v2.x, build.excludeMiddleware
и build.split
использовались для изменения того, как определенные файлы выдавались при использовании адаптера в режиме SSR.
В Astro v3.0 эти опции конфигурации сборки заменены на новые опции конфигурации адаптера SSR для выполнения тех же задач: edgeMiddleware
и functionPerRoute
.
Что делать?
Заголовок раздела Что делать?Обновите файл конфигурации Astro, чтобы теперь использовать новые опции в конфигурации адаптера напрямую.
Утратило актуальность: markdown.drafts
.
Заголовок раздела Утратило актуальность: markdown.drafts.В Astro v2.x конфигурация markdown.drafts
позволяла вам иметь черновики страниц, которые были доступны при запуске dev-сервера, но не создавались в продакшене.
В Astro v3.0 эта функция упразднена в пользу метода коллекций контента, позволяющего обрабатывать черновые страницы путем ручной фильтрации, что дает больше контроля над функцией.
Что делать?
Заголовок раздела Что делать?Чтобы продолжать помечать некоторые страницы в вашем проекте как черновики, перейдите на коллекции контента и отфильтруйте страницы вручную со свойством draft: true
frontmatter вместо этого.
Утратило актуальность: возврат простого объекта в конечных точках
Заголовок раздела Утратило актуальность: возврат простого объекта в конечных точкахВ Astro v2.x конечные точки могли возвращать простой объект, который преобразовывался в ответ в формате JSON.
В Astro v3.0 это поведение упразднено в пользу прямого возврата объекта Response
.
Что делать?
Заголовок раздела Что делать?Обновите свои конечные точки, чтобы они возвращали объект Response
напрямую.
Если вам действительно необходимо сохранить прежний формат, вы можете использовать объект ResponseWithEncoding
, но в будущем он будет устаревшим.
Изменено по умолчанию: verbatimModuleSyntax
в предустановках tsconfig.json
Заголовок раздела Изменено по умолчанию: verbatimModuleSyntax в предустановках tsconfig.jsonВ Astro v2.x настройка verbatimModuleSyntax
была выключена по умолчанию, а ее эквивалент TypeScript 4.x importsNotUsedAsValues
был включен в пресете strict
.
В Astro v3.0 параметр verbatimModuleSyntax
включен во всех пресетах.
Что делать?
Заголовок раздела Что делать?Эта опция требует, чтобы типы импортировались с использованием синтаксиса import type
.
Хотя мы рекомендуем оставить его включенным и правильно оформлять импорт типов с помощью type
(как показано выше), вы можете отключить его, установив verbatimModuleSyntax: false
в файле tsconfig.json
, если он вызывает какие-либо проблемы.
Изменено по умолчанию: порт 3000
Заголовок раздела Изменено по умолчанию: порт 3000В Astro v2.x по умолчанию Astro работал на порту 3000
.
В Astro v3.0 порт по умолчанию изменен на 4321
. 🚀
Что делать?
Заголовок раздела Что делать?Обновите все существующие ссылки на localhost:3000
, например, в тестах или в вашем README
, чтобы они отражали новый порт localhost:4321
.
Изменено по умолчанию: import.meta.env.BASE_URL trailingSlash
Заголовок раздела Изменено по умолчанию: import.meta.env.BASE_URL trailingSlashВ Astro v2.x, import.meta.env.BASE_URL
по умолчанию добавлял к настройкам base
(EN) trailingSlash (EN). trailingSlash: "ignore"
также добавлял слэш в конце строки.
Astro v3.0 больше не добавляет import.meta.env.BASE_URL
с наклонной чертой по умолчанию, а также когда задано trailingSlash: "ignore"
. (Существующее поведение base
в сочетании с trailingSlash: "always"
или trailingSlash: "never"
остается неизменным).
Что делать?
Заголовок раздела Что делать?Если ваша base
уже имеет примыкающую косую черту, то ничего менять не нужно.
Если в вашей base
нет слэша, добавьте его, если хотите сохранить предыдущее поведение по умолчанию (или trailingSlash: "ignore"
):
Изменено по умолчанию: compressHTML
Заголовок раздела Изменено по умолчанию: compressHTMLВ Astro v2.x Astro сжимал HTML только в том случае, если для параметра compressHTML
(EN) было явно установлено значение true
. По умолчанию было установлено значение false
.
Теперь Astro v3.0 сжимает HTML по умолчанию.
Что делать?
Заголовок раздела Что делать?Теперь вы можете удалить compressHTML: true
из вашей конфигурации, так как это новое поведение по умолчанию.
Теперь вы должны установить compressHTML: false
, чтобы отказаться от сжатия HTML.
Изменено по умолчанию: scopedStyleStrategy
Заголовок раздела Изменено по умолчанию: scopedStyleStrategyВ Astro v2.x значение по умолчанию для параметра scopedStyleStrategy
(EN) было "where"
.
В Astro v3.0 появилось новое значение по умолчанию: "attribute"
. По умолчанию стили теперь применяются с использованием атрибутов data-*
.
Что делать?
Заголовок раздела Что делать?Чтобы сохранить текущее значение style scoping (EN) в вашем проекте, обновите конфигурационный файл до предыдущего значения по умолчанию:
Изменено по умолчанию: inlineStyleSheets
Заголовок раздела Изменено по умолчанию: inlineStyleSheetsВ Astro v2.x все таблицы стилей проекта по умолчанию отправлялись в виде тегов ссылок. Вы могли выбрать вставку их в теги <style>
каждый раз с помощью "always"
, или вставку только таблиц стилей меньше определенного размера с помощью "auto"
, установив конфигурацию build.inlineStylesheets
(EN). По умолчанию было установлено значение never
.
В Astro v3.0 значение по умолчанию для inlineStylesheets
изменено на "auto"
. Стили, размер которых меньше, чем ViteConfig.build.assetsInlineLimit
(по умолчанию: 4kb), вставляются по умолчанию. В противном случае стили проекта передаются во внешних таблицах стилей.
Что делать?
Заголовок раздела Что делать?Если вы хотите сохранить текущее поведение проекта, установите build.inlineStylesheets
на предыдущее значение по умолчанию, "never"
:
Изменено по умолчанию: служба обработки изображений
Заголовок раздела Изменено по умолчанию: служба обработки изображенийВ Astro v2.x в качестве [службы обработки изображений по умолчанию] использовался Squoosh (/ru/guides/images/#default-image-service).
В Astro v3.0 в качестве службы обработки изображений по умолчанию теперь используется Sharp, а вместо него в настройках предлагается использовать Squoosh.
Что мне делать?
Заголовок раздела Что мне делать?При использовании строгого менеджера пакетов, например pnpm
, вам может потребоваться вручную установить Sharp в ваш проект, даже если он является зависимостью Astro:
Если вы предпочитаете продолжать использовать Squoosh для преобразования изображений, обновите свой конфиг следующим образом:
Изменено: Регистр методов HTTP запросов
Заголовок раздела Изменено: Регистр методов HTTP запросовВ Astro v2.x, Методы HTTP-запросов (EN) были написаны с использованием строчных имен функций: get
, post
, put
, all
, и del
.
В Astro v3.0 используются имена функций в верхнем регистре, включая DELETE
вместо del
.
Что делать?
Заголовок раздела Что делать?Переименуйте все функции в их эквиваленты в верхнем регистре:
get
вGET
post
вPOST
put
вPUT
all
вALL
del
кDELETE
Изменено: Множественная настройка JSX-фреймворка
Заголовок раздела Изменено: Множественная настройка JSX-фреймворкаВ Astro v2.x вы могли использовать несколько интеграций JSX-фреймворков (React, Solid, Preact) в одном проекте без необходимости определять, какие файлы принадлежат какому фреймворку.
Astro v3.0 теперь требует указать, какой фреймворк использовать для ваших файлов, с помощью новых опций include
и exclude
в конфигурации интеграции, если у вас установлено несколько фреймворков JSX. Это позволяет Astro лучше поддерживать использование одного фреймворка, а также такие продвинутые функции, как React Fast Refresh.
Что делать?
Заголовок раздела Что делать?Если вы используете несколько JSX-фреймворков в одном проекте, задайте include
(и опционально exclude
) для массива файлов и/или папок. Для включения нескольких путей к файлам можно использовать подстановочные знаки.
Мы рекомендуем размещать общие компоненты фреймворка в одной папке (например, /components/react/
и /components/solid/
), чтобы упростить указание включаемых компонентов, но это не обязательно:
Изменено: Astro.cookies.get(key)
может возвращать undefined
Заголовок раздела Изменено: Astro.cookies.get(key) может возвращать undefinedВ Astro v2.x функция Astro.cookies.get(key)
всегда возвращала объект AstroCookie
, даже если куки не существовало. Чтобы проверить его существование, нужно было использовать Astro.cookies.has(key)
.
Astro v3.0 возвращает значение undefined
для Astro.cookies.get(key)
, если куки не существует.
Что мне делать?
Заголовок раздела Что мне делать?Это изменение не нарушит работу кода, который проверяет существование объекта Astro.cookie
перед использованием Astro.cookies.get(key)
, но теперь оно больше не требуется.
Вы можете смело удалить любой код, использующий has()
для проверки того, что значение Astro.cookies
является undefined
:
Изменено: запуск Astro CLI программно
Заголовок раздела Изменено: запуск Astro CLI программноВ Astro v2.x точка входа пакета "astro"
экспортировала и запускала Astro CLI напрямую. На практике запускать Astro таким образом не рекомендуется.
В Astro v3.0 CLI удален из точки входа, и экспортируется новый набор экспериментальных API JavaScript, включая dev()
, build()
, preview()
и ync()
.
Что мне делать?
Заголовок раздела Что мне делать?Чтобы запустить Astro CLI программно, используйте новые экспериментальные API JavaScript:
Изменено: пути экспорта внутренних точек входа Astro API
Заголовок раздела Изменено: пути экспорта внутренних точек входа Astro APIВ Astro v2.x вы могли импортировать внутренние API Astro из astro/internal/*
и astro/runtime/server/*
.
В Astro v3.0 эти две точки входа удалены в пользу существующей точки входа astro/runtime/*
. Кроме того, был добавлен новый экспорт astro/compiler-runtime
для специфичного для компилятора кода времени выполнения.
Что мне делать?
Заголовок раздела Что мне делать?Это точки входа для внутреннего API Astro, и они не должны повлиять на ваш проект. Но если вы используете эти точки входа, обновите их, как показано ниже:
Ресурсы сообщества
Заголовок раздела Ресурсы сообществаЗнаете хороший ресурс по Astro v3.0? Отредактируйте эту страницу и добавьте ссылку ниже!
Известные проблемы
Заголовок раздела Известные проблемыВ настоящее время нет никаких известных проблем.
Upgrade Guides