Обновление до Astro v2
Это руководство поможет вам перейти с Astro v1 на Astro v2.
Вам нужно обновить старый проект до версии 1? Смотрите наше старое руководство по миграции.
Обновление Astro
Заголовок раздела Обновление AstroОбновите версию Astro для вашего проекта до последней версии с помощью менеджера пакетов. Если вы используете интеграции Astro, также обновите их до последней версии.
Изменения в Astro v2.0
Заголовок раздела Изменения в Astro v2.0Astro v2.0 включает в себя некоторые изменения, а также удаление некоторых ранее устаревших функций. Если после обновления до версии 2.0 ваш проект работает не так, как ожидалось, ознакомьтесь с этим руководством, чтобы получить обзор всех изменений и инструкции по обновлению вашей кодовой базы.
Полную информацию о выпуске смотрите в журнале изменений.
Удалено: Поддержка Node 14
Заголовок раздела Удалено: Поддержка Node 14Срок службы Node 14 истекает в апреле 2023 года.
Astro v2.0 полностью отказывается от поддержки Node 14, чтобы все пользователи Astro могли воспользоваться более современными возможностями Node.
Что делать?
Заголовок раздела Что делать?Убедитесь, что и ваша среда разработки, и среда развертывания используют Node 16.12.0
или более позднюю версию.
-
Проверьте локальную версию Node, используя:
Если ваша локальная среда разработки нуждается в обновлении, установите Node.
-
Проверьте собственную документацию вашей среды развертывания, чтобы убедиться, что она поддерживает Node 16.
Вы можете указать Node
16.12.0
для вашего проекта Astro либо в настройках конфигурации приборной панели, либо в файле.nvmrc
.
Зарезервировано: “src/content/`.
Заголовок раздела Зарезервировано: “src/content/`.Astro v2.0 теперь включает API Collections для организации ваших Markdown и MDX файлов в коллекции контента. Этот API резервирует src/content/
в качестве специальной папки.
Что делать?
Заголовок раздела Что делать?Переименуйте существующую папку src/content/
, чтобы избежать конфликтов. Эта папка, если она существует, теперь может использоваться только для коллекций контента.
Изменено: Astro.site
в конце слэша
Заголовок раздела Изменено: Astro.site в конце слэшаВ версии 1.x Astro следил за тем, чтобы URL, заданный в качестве site
в файле astro.config.mjs
, всегда содержал косую черту при обращении к нему с помощью Astro.site
.
Astro v2.0 больше не изменяет значение site
. Astro.site
будет использовать точное значение, и при желании необходимо указать косую черту.
Что делать?
Заголовок раздела Что делать?В файле astro.config.mjs
добавьте косую черту к URL, заданному в site
.
Изменено: папка _astro/
для ассетов сборки
Заголовок раздела Изменено: папка _astro/ для ассетов сборкиВ версии 1.x ассеты собирались в различных местах, включая assets/
, chunks/
и в корне выходных данных сборки.
В Astro v2.0 все ассеты сборки перемещены и унифицированы в новую папку _astro/
.
Директорияdist/
Директория_astro
- client.9218e799.js
- index.df3f880e0.css
Вы можете управлять этим расположением с помощью новой опции конфигурации build.assets
.
Что делать?
Заголовок раздела Что делать?Обновите конфигурацию платформы развертывания, если она зависит от расположения этих ассетов.
Изменено: Конфигурация плагина Markdown
Заголовок раздела Изменено: Конфигурация плагина MarkdownУдалено: extendDefaultPlugins
.
Заголовок раздела Удалено: extendDefaultPlugins.В версии 1.x Astro использовал markdown.extendDefaultPlugins
для повторного включения плагинов Astro по умолчанию при добавлении собственных плагинов Markdown.
В Astro v2.0 этот параметр полностью удален, поскольку его поведение теперь используется по умолчанию.
Применение плагинов remark и rehype в вашей конфигурации Markdown больше не отключает плагины Astro по умолчанию. GitHub-Flavored Markdown и Smartypants теперь применяются независимо от того, настроены ли пользовательские remarkPlugins
или rehypePlugins
.
Что делать?
Заголовок раздела Что делать?Удалите extendDefaultPlugins
в вашей конфигурации. Теперь это поведение Astro по умолчанию в версии 2.0, и вы можете удалить эту строку без какой-либо замены.
Добавлено: gfm
и smartypants
.
Заголовок раздела Добавлено: gfm и smartypants.В версии 1.x вы могли отключить оба стандартных плагина Astro для работы с Markdown (GitHub-Flavored Markdown и SmartyPants), установив markdown.extendDefaultPlugins: false
.
В Astro v2.0 параметр markdown.extendDefaultPlugins: false
заменен на отдельные булевы опции для индивидуального управления каждым из встроенных в Astro плагинов Markdown по умолчанию. Они включены по умолчанию и могут быть установлены на false
независимо друг от друга.
Что делать?
Заголовок раздела Что делать?Удалите extendDefaultPlugins: false
и добавьте вместо этого флаги для отключения каждого плагина по отдельности.
markdown.gfm: false
отключает GitHub-Flavored Markdownmarkdown.smartypants: false
отключает SmartyPants
Изменено: Конфигурация MDX-плагина
Заголовок раздела Изменено: Конфигурация MDX-плагинаЗаменено: extendPlugins
заменено на extendMarkdownConfig
.
Заголовок раздела Заменено: extendPlugins заменено на extendMarkdownConfig.В версии 1.x опция extendPlugins
интеграции MDX управляла тем, как ваши MDX файлы должны наследовать вашу конфигурацию Markdown: всю вашу конфигурацию Markdown (markdown
), или только плагины Astro по умолчанию (default
).
В Astro v2.0 поведение, контролируемое mdx.extendPlugins
, заменено тремя новыми, независимо настраиваемыми опциями, которые по умолчанию имеют значение true
:
mdx.extendMarkdownConfig
чтобы наследовать все или ничего из вашей конфигурации Markdownmdx.gfm
для включения или отключения GitHub-Flavored Markdown в MDXmdx.smartypants
для включения или отключения SmartyPants в MDX
Что мне делать?
Заголовок раздела Что мне делать?Удалите extendPlugins: 'markdown'
в вашей конфигурации. Теперь это поведение по умолчанию.
Замените extendPlugins: 'defaults'
на extendMarkdownConfig: false
и добавьте отдельные опции для GitHub-Flavored Markdown и SmartyPants, чтобы включить эти плагины по умолчанию по отдельности в MDX.
Добавлено: Больше опций конфигурации MDX для соответствия Markdown
Заголовок раздела Добавлено: Больше опций конфигурации MDX для соответствия MarkdownAstro v2.0 позволяет вам теперь отдельно устанавливать все доступные опции конфигурации Markdown (кроме drafts
) в конфигурации интеграции MDX.
Что мне делать?
Заголовок раздела Что мне делать?Пересмотрите свою конфигурацию Markdown и MDX и сравните существующий конфиг с новыми доступными опциями.
Изменено: Доступ плагинов к frontmatter
Заголовок раздела Изменено: Доступ плагинов к frontmatterВ версии 1.x плагины remark и rehype не имели доступа к пользовательскому frontmatter. Astro объединял frontmatter плагина с frontmatter вашего файла, не передавая frontmatter файла вашим плагинам.
Astro v2.0 предоставляет плагинам remark и rehype доступ к пользовательскому frontmatter через инъекцию frontmatter. Это позволяет авторам плагинов изменять существующий frontmatter пользователя или вычислять новые свойства на основе других свойств.
Что делать?
Заголовок раздела Что делать?Проверьте все написанные вами плагины remark и rehype, чтобы узнать, не изменилось ли их поведение. Обратите внимание, что data.astro.frontmatter
теперь является полным frontmatter’ом документа Markdown или MDX, а не пустым объектом.
Изменено: Конфигурация RSS
Заголовок раздела Изменено: Конфигурация RSSВ версии 1.x пакет RSS Astro позволял вам использовать items: import.meta.glob(...)
для создания списка элементов RSS-ленты. Сейчас это использование устарело и со временем будет удалено.
В Astro v2.0 появилась обертка pagesGlobToRssItems()
для свойства items
.
Что делать?
Заголовок раздела Что делать?Импортируйте, а затем оберните вашу существующую функцию, содержащую import.meta.glob()
, помощником pagesGlobToRssItems()
.
Изменено: Поддержка Svelte IDE
Заголовок раздела Изменено: Поддержка Svelte IDEAstro v2.0 требует наличия файла svelte.config.js в вашем проекте, если вы используете [интеграцию
@astrojs/svelte`](/ru/guides/integrations-guide/svelte/). Это необходимо для обеспечения автодополнения в IDE.
Что делать?
Заголовок раздела Что делать?Добавьте файл `svelte.config.js в корень вашего проекта:
Для новых пользователей этот файл будет добавлен автоматически при выполнении команды astro add svelte
.
Удалено: legacy.astroFlavoredMarkdown
.
Заголовок раздела Удалено: legacy.astroFlavoredMarkdown.В версии 1.0 Astro переместил старый Astro-Flavored Markdown (также известный как Components in Markdown) в унаследованную функцию.
В Astro v2.0 опция legacy.astroFlavoredMarkdown
полностью удалена. Импорт и использование компонентов в файлах .md
больше не будет работать.
Что делать?
Заголовок раздела Что делать?Удалите этот флаг наследия. Он больше не доступен в Astro.
Если вы использовали эту функцию в версии 1.x, мы рекомендуем использовать интеграцию MDX, которая позволяет комбинировать компоненты и JSX-выражения с синтаксисом Markdown.
Удалено: Astro.resolve()
.
Заголовок раздела Удалено: Astro.resolve().В версии 0.24 Astro устарела функция Astro.resolve()
для получения разрешенных URL-адресов активов, на которые вы можете захотеть сослаться в браузере.
В Astro v2.0 эта опция полностью удалена. Использование Astro.resolve()
в вашем коде приведет к ошибке.
Что делать?
Заголовок раздела Что делать?Вместо этого разрешайте пути к активам с помощью import
. Например:
Удалено: Astro.fetchContent()
.
Заголовок раздела Удалено: Astro.fetchContent().В версии 0.26 Astro устарела опция Astro.fetchContent()
для получения данных из ваших локальных файлов Markdown.
В версии Astro v2.0 эта опция полностью удалена. Использование Astro.fetchContent()
в вашем коде приведет к ошибке.
Что делать?
Заголовок раздела Что делать?Используйте Astro.glob()
для получения файлов Markdown, или перейдите на Коллекцию Контента.
Удалено: Astro.canonicalURL
.
Заголовок раздела Удалено: Astro.canonicalURL.В версии 1.0 Astro устарела функция Astro.canonicalURL
для построения канонического URL.
В Astro v2.0 эта опция полностью удалена. Использование Astro.canonicalURL
в вашем коде приведет к ошибке.
Что делать?
Заголовок раздела Что делать?Используйте Astro.url
для построения канонического URL.
Обновлено: Vite 4
Заголовок раздела Обновлено: Vite 4Astro v2.0 обновляется с Vite 3 до Vite 4, который выйдет в декабре 2022 года.
Что мне делать?
Заголовок раздела Что мне делать?Никаких изменений в вашем коде не должно быть! Мы выполнили большую часть обновления за вас внутри Astro; однако некоторые тонкости поведения Vite могут измениться между версиями.
Обратитесь к официальному руководству Vite Migration Guide, если у вас возникнут проблемы.
Удалены экспериментальные флаги Astro v2.0
Заголовок раздела Удалены экспериментальные флаги Astro v2.0Удалите следующие экспериментальные флаги из astro.config.mjs
:
Эти функции теперь доступны по умолчанию:
- Коллекции контента как способ управления файлами Markdown и MDX с безопасностью типов.
- Предрендеринг отдельных страниц в статический HTML при использовании SSR для повышения скорости и кэшируемости.
- Переработанный оверлей сообщений об ошибках.
Известные проблемы
Заголовок раздела Известные проблемыВ настоящее время известных проблем нет.
Upgrade Guides