升级到 Astro v4

本指南将帮助你从 Astro v3 迁移到 Astro v4。

需要将旧项目升级到 v3 吗？请参阅我们的 旧版本迁移指南。

需要查阅 v3 的文档？请访问这个旧版本文档站 (不被维护的 v3.6 快照)。

升级 Astro

段落标题 升级 Astro

使用你的包管理器将项目的 Astro 和所有官方集成升级到最新版本。

npm

# 同时升级 Astro 和官方集成
npx @astrojs/upgrade

pnpm

# 同时升级 Astro 和官方集成
pnpm dlx @astrojs/upgrade

Yarn

# 同时升级 Astro 和官方集成
yarn dlx @astrojs/upgrade

如果需要的话，你也可以手动升级 Astro 集成，你可能还需要升级项目中的其他依赖。

需要继续吗？

升级 Astro 到最新版本后，你可能不需要对你的项目做任何更改！

但是，如果你遇到错误或意外的行为，请检查下面的内容，看看有什么变化可能需要在你的项目中更新。

Astro v4.0 包含潜在的破坏性，以及一些之前被弃用的功能被移除。

如果你的项目在升级后的行为不符合预期，请参考本指南，了解所有破坏性更改的概述以及如何修改你的代码的说明。

完整的发行说明请参阅 changelog。

Astro v4.0 移除的实验性标志

段落标题 Astro v4.0 移除的实验性标志

从 astro.config.mjs 中移除 devOverlay 实验性标志并把 i18n 移到最外层：

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    devOverlay: true,
    i18n: {
      locales: ["en", "fr", "pt-br", "es"],
      defaultLocale: "en",
    }
  },
  i18n: {
    locales: ["en", "fr", "pt-br", "es"],
    defaultLocale: "en",
  },
})

这些功能现已可在 Astro v4.0 中使用。

了解更多关于这两个令人兴奋的功能以及更多内容，请阅读 v4.0 博客文章！

升级

段落标题 升级

可能导致你的项目中出现不兼容的 major 版本更新。

已升级：Vite 5.0

段落标题 已升级：Vite 5.0

在 Astro v3.0 中，开发服务器和生产打包工具使用的是 Vite 4。

Astro v4.0 从 Vite 4 升级到了 Vite 5。

我应该做什么？

段落标题 我应该做什么？

如果你使用了 Vite 的插件、配置或 API，请查看 Vite 迁移指南中的破坏性更改并根据需要升级你的项目。Astro 本身没有任何破坏性更改。

已升级：unified、remark、和 rehype 依赖

段落标题 已升级：unified、remark、和 rehype 依赖

在 Astro v3.0 中，处理 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 之前的文档快照。

重命名：entrypoint (集成 API)

段落标题 重命名：entrypoint (集成 API)

在 Astro v3.0 中，集成 API injectRoute 用于指定路由入口点的的属性名字是 entryPoint。

Astro v4.0 为了与其他 Astro API 的一致性把它改为 entrypoint。entryPoint 属性已被弃用，它还能被使用但会输出一条警告提醒你更新你的代码。

我应该做什么？

段落标题 我应该做什么？

如果你有使用了 injectRoute API 的集成，请把 entryPoint 属性改为 entrypoint。如果你是一个库的作者，想要同时支持 Astro 3 和 4，你可以同时指定 entryPoint 和 entrypoint，这样就不会输出警告。

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

改动：集成 API app.render 的函数签名

段落标题 改动：集成 API app.render 的函数签名

在 Astro v3.0 中，app.render() 方法接收互相独立独立、可选的 routeData 和 locals 参数。

Astro v4.0 修改了 app.render() 的函数签名。这两个属性现在在同一个对象里。这个对象和这两个属性仍旧是可选的。

我应该做什么？

段落标题 我应该做什么？

如果你维护了一个适配器，当前的函数签名将会继续工作到下一个 major 版本。要迁移到新的签名，把 routeData 和 locals 作为一个对象的属性传递，而不是作为多个独立的参数。

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

改动：适配器现在必须指定所支持的功能

段落标题 改动：适配器现在必须指定所支持的功能

在 Astro v3.0 中，适配器不需要指定它们所支持的功能。

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'
          }
        });
      },
    },
  };
}

移除：Shiki 语言 path 属性

段落标题 移除：Shiki 语言 path 属性

在 Astro v3.0 中，一个传入 markdown.shikiConfig.langs 的 Shiki language 会被自动转换成一个兼容 Shikiji 的语言。Shikiji 是 Astro 内部使用的语言高亮工具。

Astro v4.0 移除了对 Shiki 语言的 path 属性的支持，这个属性配置起来令人困惑。它被一个可以直接传入 langs 的导入替代。

我应该做什么？

段落标题 我应该做什么？

语言 JSON 文件应该被导入并传入到选项中。

astro.config.js

 import customLang from './custom.tmLanguage.json'

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

弃用

段落标题 弃用

下面的这些功能在 Astro v4.0 中已不再被支持，也不再被文档记录。请相应地更新你的项目。

部分弃用的功能可能暂时会在 Astro v4.0 中继续工作，直到它们被完全移除。其他的可能会默默地没有任何效果，或者抛出一个错误提示你更新你的代码。

弃用：视图过渡 submit 事件的 handleForms

段落标题 弃用：视图过渡 submit 事件的 handleForms

在 Astro v3.0 中，使用了 <ViewTransitions /> 组件的项目必须 opt-in 处理 form 元素的 submit 事件。这是通过传入一个 handleForms 参数实现的。

Astro v4.0 在使用 <ViewTransitions /> 时默认处理 form 元素的 submit 事件。handleForms 参数已被弃用且没有任何效果。

我应该做什么？

段落标题 我应该做什么？

从你的 ViewTransitions 组件中移除 handleForms 属性。它已不被需要。

src/pages/index.astro

---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- 一些内容 -->
  </body>
</html>

Otomatik - 15.197.167.90 CloudFlare DNS Türk Telekom DNS Google DNS Open DNS

OSZAR »

">