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

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

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

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

Нужно посмотреть документацию по v3? Посетите этот сайт старая версия документации (не поддерживаемый снимок v3.6).

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

Окно терминала
# Обновление Astro и официальных интеграций
npx @astrojs/upgrade

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

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

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

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

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

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

Удалите экспериментальный флаг devOverlay и переместите любую конфигурацию i18n на верхний уровень в astro.config.mjs:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
devOverlay: true,
i18n: {
defaultLocale: "en",
locales: ["en", "fr", "pt-br", "es"],
}
},
i18n: {
defaultLocale: "en",
locales: ["en", "fr", "pt-br", "es"],
},
})

Эти конфигурации, i18n и переименованная devToolbar, теперь доступны в Astro v4.0.

Подробнее об этих двух интересных функциях и многом другом читайте в посте v4.0 в Блоге!

Любые крупные обновления зависимостей Astro могут привести к изменениям в вашем проекте.

В Astro v3.0 Vite 4 использовался в качестве сервера разработки и производственного бандлера.

Astro v4.0 переходит с Vite 4 на Vite 5.

Если вы используете специфические для Vite плагины, конфигурации или API, проверьте руководство по миграции Vite на наличие изменений и обновите свой проект при необходимости. В самом Astro никаких изменений нет.

Обновлено: зависимости unified, remark и rehype

Заголовок раздела Обновлено: зависимости unified, remark и rehype

В Astro v3.x для обработки Markdown и MDX использовался unified v10 и связанные с ним совместимые пакеты remark/rehype.

Astro v4.0 обновляет unified до v11 и другие пакеты remark/rehype до последней версии.

Если вы использовали пользовательские пакеты remark/rehype, обновите их до последней версии с помощью менеджера пакетов, чтобы убедиться, что они поддерживают unified v11. Используемые вами пакеты можно найти в файле astro.config.mjs.

При использовании активно обновляемых пакетов не должно произойти никаких существенных изменений, но некоторые пакеты могут быть еще не совместимы с unified v11. Перед развертыванием визуально проверьте свои Markdown/MDX-страницы, чтобы убедиться, что ваш сайт работает так, как нужно.

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

Если вам нужно обратиться к документации по проекту v3.x, вы можете просмотреть этот (не поддерживаемый) снимок документации до выхода v4.0.

В Astro v3.x свойство API интеграций injectRoute, указывающее точку входа в маршрут, называлось entryPoint.

В Astro v4.0 это свойство переименовано в entrypoint, чтобы соответствовать другим API Astro. Свойство entryPoint устарело, но будет продолжать работать и выводить в журнал предупреждение с предложением обновить код.

Если у вас есть интеграции, использующие API injectRoute, переименуйте свойство entryPoint в entrypoint. Если вы автор библиотеки, которая хочет поддерживать и Astro 3, и Astro 4, вы можете указать и entryPoint, и entrypoint, и в этом случае предупреждение не будет регистрироваться.

injectRoute({
pattern: '/fancy-dashboard',
entryPoint: '@fancy/dashboard/dashboard.astro'
entrypoint: '@fancy/dashboard/dashboard.astro'
});

Изменено: сигнатура app.render в API интеграций

Заголовок раздела Изменено: сигнатура app.render в API интеграций

В Astro v3.0 метод app.render() принимал routeData и locals как отдельные, необязательные аргументы.

В версии Astro v4.0 сигнатура метода app.render() была изменена. Теперь эти два свойства доступны в одном объекте. Объект и эти два свойства по-прежнему необязательны.

Если вы поддерживаете адаптер, текущая сигнатура будет работать до следующей основной версии. Чтобы перейти на новую сигнатуру, передавайте routeData и locals как свойства объекта, а не как несколько независимых аргументов.

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

Изменено: адаптеры теперь должны указывать поддерживаемые функции

Заголовок раздела Изменено: адаптеры теперь должны указывать поддерживаемые функции

В Astro v3.x от адаптеров не требовалось указывать поддерживаемые ими функции.

Astro v4.0 требует, чтобы адаптеры передавали свойство supportedAstroFeatures{} для указания списка поддерживаемых ими функций. Это свойство больше не является необязательным.

Авторам адаптеров необходимо передавать свойство supportedAstroFeatures{}, чтобы указать список поддерживаемых ими функций.

my-adapter.mjs
export default function createIntegration() {
return {
name: '@matthewp/my-adapter',
hooks: {
'astro:config:done': ({ setAdapter }) => {
setAdapter({
name: '@matthewp/my-adapter',
serverEntrypoint: '@matthewp/my-adapter/server.js',
supportedAstroFeatures: {
staticOutput: 'stable'
}
});
},
},
};
}

В Astro v3.x язык Shiki, переданный в markdown.shikiConfig.langs, автоматически преобразовывался в язык, совместимый с Shikiji. Shikiji - это внутренний инструментарий, используемый Astro для подсветки синтаксиса.

В Astro v4.0 удалена поддержка свойства path для языка Shiki, которое вызывало путаницу при настройке. Оно заменено импортом, который может быть передан в langs напрямую.

Вместо этого следует импортировать JSON-файл языка и передать его в опцию.

astro.config.js
import customLang from './custom.tmLanguage.json'
export default defineConfig({
markdown: {
shikiConfig: {
langs: [
{ path: '../../custom.tmLanguage.json' },
customLang,
],
},
},
})

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

Некоторые устаревшие функции могут временно продолжать работать, пока не будут полностью удалены. Другие могут не иметь никакого эффекта или выдавать ошибку, побуждающую вас обновить код.

Утратило актуальность: handleForms для событий submit Анимаций Переходов

Заголовок раздела Утратило актуальность: handleForms для событий submit Анимаций Переходов

В Astro v3.x проекты, использующие компонент <ViewTransitions />, должны были отказаться от обработки событий submit для элементов form. Это делалось путем передачи свойства handleForms.

Astro v4.0 обрабатывает события submit для элементов form по умолчанию, когда используются <ViewTransitions />. Свойство handleForms было устаревшим и больше не имеет никакого значения.

Удалите свойство handleForms из компонента ViewTransitions. В нем больше нет необходимости.

src/pages/index.astro
---
import { ViewTransitions } from "astro:transitions";
---
<html>
<head>
<ViewTransitions handleForms />
</head>
<body>
<!-- здесь всякие штуки -->
</body>
</html>

Чтобы отказаться от обработки события submit, добавьте атрибут data-astro-reload к соответствующим элементам form.

src/components/Form.astro
<form action="/contact" data-astro-reload>
<!-- -->
</form>

Ранее устаревшие функции теперь удалены

Заголовок раздела Ранее устаревшие функции теперь удалены

Следующие устаревшие функции были полностью удалены из кодовой базы и больше не могут быть использованы. Некоторые из этих функций могли продолжать работать в вашем проекте даже после удаления. Другие могли не иметь никакого эффекта.

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

Удалено: возврат простых объектов из конечных точек

Заголовок раздела Удалено: возврат простых объектов из конечных точек

В Astro v3.x возврат простых объектов из конечных точек был устаревшим, но все еще поддерживался для сохранения совместимости с Astro v2. Для облегчения перехода была также предоставлена утилита ResponseWithEncoding.

В Astro v4.0 поддержка простых объектов удалена, и конечные точки должны всегда возвращать Response. Утилита ResponseWithEncoding также удалена в пользу правильного типа Response.

Обновите свои конечные точки, чтобы они возвращали объект Response напрямую.

export async function GET() {
return { body: { "title": "Bob's blog" }};
return new Response(JSON.stringify({ "title": "Bob's blog" }));
}

Чтобы отказаться от использования ResponseWithEncoding, переделайте ваш код для использования ArrayBuffer вместо этого:

export async function GET() {
const file = await fs.readFile('./bob.png');
return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
return new Response(file.buffer);
}

В Astro v3.0 опции конфигурации сборки build.split и build.excludeMiddleware были устаревшими и заменены на опции конфигурации адаптера для выполнения тех же задач.

В Astro v4.0 эти свойства полностью удалены.

Если вы используете устаревшие свойства build.split или build.excludeMiddleware, вам необходимо удалить их, так как они больше не существуют.

См. руководство по переходу на v3 для обновления этих устаревших свойств промежуточного ПО с конфигурациями адаптеров.

В Astro v3.0 API Astro.request.params был устаревшим, но сохранен для обратной совместимости.

В Astro v4.0 эта опция полностью удалена.

Обновите все упоминания на Astro.params, который является поддерживаемой заменой.

const { id } = Astro.request.params;
const { id } = Astro.params;

В Astro v3.0 использование markdown.drafts для управления созданием черновиков постов было устаревшим.

В Astro v4.0 эта опция полностью удалена.

Если вы использовали устаревшую опцию markdown.drafts, то теперь вы должны удалить ее, так как она больше не существует.

Чтобы продолжать помечать некоторые страницы в проекте как черновики, используйте миграцию в коллекции контента и ручную фильтрацию страниц со свойством draft: true frontmatter вместо этого.

В Astro v3.0 экспорт getHeaders() в Markdown был устаревшим и заменен на getHeadings().

В Astro v4.0 эта опция полностью удалена.

Если вы используете устаревшую опцию getHeaders(), вы должны удалить ее, так как она больше не существует. Замените все его экземпляры на getHeadings(), который является поддерживаемой заменой.

const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();

В Astro v3.0 использование устаревшего помощника rss в getStaticPaths() приводило к ошибке.

В Astro v4.0 этот помощник полностью удален.

Если вы используете неподдерживаемый метод генерации RSS-каналов, теперь вы должны использовать интеграцию @astrojs/rss для полной настройки RSS.

Удалено: имена HTTP-методов в нижнем регистре

Заголовок раздела Удалено: имена HTTP-методов в нижнем регистре

В Astro v3.0 использование имен методов HTTP-запросов в нижнем регистре (get, post, put, all, del) было устаревшим.

В Astro v4.0 поддержка строчных имен полностью удалена. Все методы HTTP-запросов теперь должны быть написаны в верхнем регистре.

Если вы используете устаревшие имена в нижнем регистре, теперь вы должны заменить их на эквиваленты в верхнем регистре.

Обратитесь к руководству по миграции на v3 для руководства по использованию методов HTTP-запросов в верхнем регистре.

Удалено: 301 редирект при отсутствии префикса base

Заголовок раздела Удалено: 301 редирект при отсутствии префикса base

В Astro v3.x сервер предпросмотра Astro возвращал 301 перенаправление при доступе к ресурсам из публичной директории без пути base.

В Astro v4.0, когда сервер предпросмотра запущен, при доступе к ресурсам из публичной директории без префикса пути base возвращается статус 404, соответствующий поведению сервера разработки.

При использовании сервера предварительного просмотра Astro все импортируемые статические активы и URL-адреса из публичной директории должны иметь префикс значения base к пути.

В следующем примере показан атрибут src, необходимый для отображения изображения из публичной папки, когда base: '/docs' настроен:

src/pages/index.astro
// Для доступа к public/images/my-image.png:
<img src="/docs/images/my-image.png" alt="">.

В Astro v3.x тип astro/client-image (используемый для устаревшей интеграции изображений) был удален, но автоматически преобразовывался в стандартный тип Astro astro/client, если был найден в вашем файле env.d.ts.

Astro v4.0 игнорирует astro/client-image и больше не будет обновлять env.d.ts для вас автоматически.

Если у вас были настроены типы для @astrojs/image в src/env.d.ts и обновление до v3.0 не привело к автоматическому преобразованию типов, замените тип astro/client-image вручную на astro/client.

src/env.d.ts
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />

Знаете хороший ресурс по Astro v4.0? Отредактируйте эту страницу и добавьте ссылку ниже!

Пожалуйста, проверьте Проблемы Astro на GitHub, чтобы узнать о любых известных проблемах, или чтобы создать проблему самостоятельно.

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

Что у вас на уме?

Сообщество