Перейти к содержимому

Обновление до Astro v2

Это руководство поможет вам перейти с Astro v1 на Astro v2.

Вам нужно обновить старый проект до версии 1? Смотрите наше старое руководство по миграции.

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

Окно терминала
# Обновление до Astro v2.x
npm install astro@latest
# Пример: обновление интеграций React и Tailwind
npm install @astrojs/react@latest @astrojs/tailwind@latest

Astro v2.0 включает в себя некоторые изменения, а также удаление некоторых ранее устаревших функций. Если после обновления до версии 2.0 ваш проект работает не так, как ожидалось, ознакомьтесь с этим руководством, чтобы получить обзор всех изменений и инструкции по обновлению вашей кодовой базы.

Полную информацию о выпуске смотрите в журнале изменений.

Срок службы Node 14 истекает в апреле 2023 года.

Astro v2.0 полностью отказывается от поддержки Node 14, чтобы все пользователи Astro могли воспользоваться более современными возможностями Node.

Убедитесь, что и ваша среда разработки, и среда развертывания используют Node 16.12.0 или более позднюю версию.

  1. Проверьте локальную версию Node, используя:

    Окно терминала
    node -v

    Если ваша локальная среда разработки нуждается в обновлении, установите Node.

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

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

Astro v2.0 теперь включает API Collections для организации ваших Markdown и MDX файлов в коллекции контента. Этот API резервирует src/content/ в качестве специальной папки.

Переименуйте существующую папку src/content/, чтобы избежать конфликтов. Эта папка, если она существует, теперь может использоваться только для коллекций контента.

В версии 1.x Astro следил за тем, чтобы URL, заданный в качестве site в файле astro.config.mjs, всегда содержал косую черту при обращении к нему с помощью Astro.site.

Astro v2.0 больше не изменяет значение site. Astro.site будет использовать точное значение, и при желании необходимо указать косую черту.

В файле astro.config.mjs добавьте косую черту к URL, заданному в site.

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
site: 'https://example.com',
site: 'https://example.com/',
});

Изменено: папка _astro/ для ассетов сборки

Заголовок раздела Изменено: папка _astro/ для ассетов сборки

В версии 1.x ассеты собирались в различных местах, включая assets/, chunks/ и в корне выходных данных сборки.

В Astro v2.0 все ассеты сборки перемещены и унифицированы в новую папку _astro/.

  • Директорияdist/
    • Директория_astro
      • client.9218e799.js
      • index.df3f880e0.css

Вы можете управлять этим расположением с помощью новой опции конфигурации build.assets.

Обновите конфигурацию платформы развертывания, если она зависит от расположения этих ассетов.

В версии 1.x Astro использовал markdown.extendDefaultPlugins для повторного включения плагинов Astro по умолчанию при добавлении собственных плагинов Markdown.

В Astro v2.0 этот параметр полностью удален, поскольку его поведение теперь используется по умолчанию.

Применение плагинов remark и rehype в вашей конфигурации Markdown больше не отключает плагины Astro по умолчанию. GitHub-Flavored Markdown и Smartypants теперь применяются независимо от того, настроены ли пользовательские remarkPlugins или rehypePlugins.

Удалите extendDefaultPlugins в вашей конфигурации. Теперь это поведение Astro по умолчанию в версии 2.0, и вы можете удалить эту строку без какой-либо замены.

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins,
}
});

В версии 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 Markdown
  • markdown.smartypants: false отключает SmartyPants
astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins: false,
smartypants: false,
gfm: false,
}
});

Заменено: extendPlugins заменено на extendMarkdownConfig.

Заголовок раздела Заменено: extendPlugins заменено на extendMarkdownConfig.

В версии 1.x опция extendPlugins интеграции MDX управляла тем, как ваши MDX файлы должны наследовать вашу конфигурацию Markdown: всю вашу конфигурацию Markdown (markdown), или только плагины Astro по умолчанию (default).

В Astro v2.0 поведение, контролируемое mdx.extendPlugins, заменено тремя новыми, независимо настраиваемыми опциями, которые по умолчанию имеют значение true:

  • mdx.extendMarkdownConfig чтобы наследовать все или ничего из вашей конфигурации Markdown
  • mdx.gfm для включения или отключения GitHub-Flavored Markdown в MDX
  • mdx.smartypants для включения или отключения SmartyPants в MDX

Удалите extendPlugins: 'markdown' в вашей конфигурации. Теперь это поведение по умолчанию.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
extendPlugins: 'markdown',
}),
],
});

Замените extendPlugins: 'defaults' на extendMarkdownConfig: false и добавьте отдельные опции для GitHub-Flavored Markdown и SmartyPants, чтобы включить эти плагины по умолчанию по отдельности в MDX.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
extendPlugins: 'defaults',
extendMarkdownConfig: false,
smartypants: true,
gfm: true,
}),
],
});

Добавлено: Больше опций конфигурации MDX для соответствия Markdown

Заголовок раздела Добавлено: Больше опций конфигурации MDX для соответствия Markdown

Astro v2.0 позволяет вам теперь отдельно устанавливать все доступные опции конфигурации Markdown (кроме drafts) в конфигурации интеграции MDX.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
remarkPlugins: [remarkPlugin1],
gfm: true,
},
integrations: [
mdx({
remarkPlugins: [remarkPlugin2],
gfm: false,
})
]
});

Пересмотрите свою конфигурацию Markdown и MDX и сравните существующий конфиг с новыми доступными опциями.

В версии 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, а не пустым объектом.

В версии 1.x пакет RSS Astro позволял вам использовать items: import.meta.glob(...) для создания списка элементов RSS-ленты. Сейчас это использование устарело и со временем будет удалено.

В Astro v2.0 появилась обертка pagesGlobToRssItems() для свойства items.

Импортируйте, а затем оберните вашу существующую функцию, содержащую import.meta.glob(), помощником pagesGlobToRssItems().

src/pages/rss.xml.js
import rss, {
pagesGlobToRssItems
} from '@astrojs/rss';
export async function get(context) {
return rss({
items: await pagesGlobToRssItems(
import.meta.glob('./blog/*.{md,mdx}'),
),
});
}

Astro v2.0 требует наличия файла svelte.config.js в вашем проекте, если вы используете [интеграцию @astrojs/svelte`](/ru/guides/integrations-guide/svelte/). Это необходимо для обеспечения автодополнения в IDE.

Добавьте файл `svelte.config.js в корень вашего проекта:

svelte.config.js
import { vitePreprocess } from '@astrojs/svelte';
export default {
preprocess: vitePreprocess(),
};

Для новых пользователей этот файл будет добавлен автоматически при выполнении команды astro add svelte.

В версии 1.0 Astro переместил старый Astro-Flavored Markdown (также известный как Components in Markdown) в унаследованную функцию.

В Astro v2.0 опция legacy.astroFlavoredMarkdown полностью удалена. Импорт и использование компонентов в файлах .md больше не будет работать.

Удалите этот флаг наследия. Он больше не доступен в Astro.

astro.config.mjs
export default defineConfig({
legacy: {
astroFlavoredMarkdown: true,
},
})

Если вы использовали эту функцию в версии 1.x, мы рекомендуем использовать интеграцию MDX, которая позволяет комбинировать компоненты и JSX-выражения с синтаксисом Markdown.

В версии 0.24 Astro устарела функция Astro.resolve() для получения разрешенных URL-адресов активов, на которые вы можете захотеть сослаться в браузере.

В Astro v2.0 эта опция полностью удалена. Использование Astro.resolve() в вашем коде приведет к ошибке.

Вместо этого разрешайте пути к активам с помощью import. Например:

src/pages/index.astro
---
import 'style.css';
import imageUrl from './image.png';
---
<img src={imageUrl} />

В версии 0.26 Astro устарела опция Astro.fetchContent() для получения данных из ваших локальных файлов Markdown.

В версии Astro v2.0 эта опция полностью удалена. Использование Astro.fetchContent() в вашем коде приведет к ошибке.

Используйте Astro.glob() для получения файлов Markdown, или перейдите на Коллекцию Контента.

src/pages/index.astro
---
const allPosts = await Astro.glob('./posts/*.md');
---

В версии 1.0 Astro устарела функция Astro.canonicalURL для построения канонического URL.

В Astro v2.0 эта опция полностью удалена. Использование Astro.canonicalURL в вашем коде приведет к ошибке.

Используйте Astro.url для построения канонического URL.

src/pages/index.astro
---
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
---

Astro v2.0 обновляется с Vite 3 до Vite 4, который выйдет в декабре 2022 года.

Никаких изменений в вашем коде не должно быть! Мы выполнили большую часть обновления за вас внутри Astro; однако некоторые тонкости поведения Vite могут измениться между версиями.

Обратитесь к официальному руководству Vite Migration Guide, если у вас возникнут проблемы.

Удалены экспериментальные флаги Astro v2.0

Заголовок раздела Удалены экспериментальные флаги Astro v2.0

Удалите следующие экспериментальные флаги из astro.config.mjs:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
contentCollections: true,
prerender: true,
errorOverlay: true,
},
})

Эти функции теперь доступны по умолчанию:

В настоящее время известных проблем нет.