升级到 Astro v4

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

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

需要查看 v3 文档？请访问此旧版文档网站（一个未经维护的 v3.6 快照）。

升级 Astro

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

npm

# Upgrade Astro and official integrations together
npx @astrojs/upgrade

pnpm

# Upgrade Astro and official integrations together
pnpm dlx @astrojs/upgrade

Yarn

# Upgrade Astro and official integrations together
yarn dlx @astrojs/upgrade

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

需要继续吗？

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

但是，如果你发现错误或意外行为，请查看下面的内容，了解哪些更改可能需要在你的项目中进行更新。

Astro v4.0 包含一些潜在的破坏性变更，以及移除了一些先前已废弃的特性。

如果你的项目在升级到 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: {
      locales: ["en", "fr", "pt-br", "es"],
      defaultLocale: "en",
    }
  },
  i18n: {
    locales: ["en", "fr", "pt-br", "es"],
    defaultLocale: "en",
  },
})

这些配置，i18n 和重命名后的 devToolbar，现在在 Astro v4.0 中可用。

在 v4.0 博客文章中阅读更多关于这两个激动人心的功能和其他内容！

升级

Astro 依赖项的任何重大升级都可能在你的项目中导致破坏性变更。

升级：Vite 5.0

在 Astro v3.0 中，Vite 4 被用作开发服务器和生产打包器。

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

我应该怎么做？

如果你正在使用 Vite 特定的插件、配置或 API，请查看 Vite 迁移指南以了解其破坏性变更，并根据需要升级你的项目。Astro 本身没有破坏性变更。

升级：unified、remark 和 rehype 依赖

在 Astro v3.x 中，unified v10 及其相关的兼容 remark/rehype 包被用于处理 Markdown 和 MDX。

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）

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

Astro v4.0 将此属性重命名为 entrypoint 以与其他 Astro API 保持一致。`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 签名

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

移除：Shiki 语言 path 属性

在 Astro v3.x 中，传递给 markdown.shikiConfig.langs 的 Shiki 语言会自动转换为与 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,
      ],
    },
  },
})

已弃用

以下已废弃的特性不再被支持，也不再被记录在文档中。请相应地更新你的项目。

一些已废弃的特性可能会在被完全移除之前暂时继续工作。其他的可能会悄无声息地不起作用，或者抛出一个错误提示你更新代码。

废弃：用于视图转换（View Transitions）submit 事件的 handleForms

在 Astro v3.x 中，使用 <ViewTransitions /> 组件的项目需要选择性地加入对 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>
    <!-- stuff here -->
  </body>
</html>

要退出 submit 事件处理，请向相关的 form 元素添加 data-astro-reload 属性。

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

移除：build.split 和 build.excludeMiddleware

在 Astro v3.0 中，build.split 和 build.excludeMiddleware 构建配置选项已被废弃，并被适配器配置选项所取代以执行相同的任务。

Astro v4.0 完全移除了这些属性。

我应该怎么做？

如果你正在使用已废弃的 build.split 或 build.excludeMiddleware，你现在必须移除它们，因为它们已不再存在。

请参阅 v3 迁移指南，用适配器配置更新这些已废弃的中间件属性。

移除：Astro.request.params

在 Astro v3.0 中，Astro.request.params API 已被废弃，但为了向后兼容而保留。

Astro v4.0 完全移除了这个选项。

我应该怎么做？

将所有出现的地方更新为Astro.params，这是受支持的替代品。

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

移除：markdown.drafts

在 Astro v3.0 中，使用 markdown.drafts 来控制草稿文章的构建已被废弃。

Astro v4.0 完全移除了这个选项。

我应该怎么做？

如果你正在使用已废弃的 markdown.drafts，你现在必须移除它，因为它已不再存在。

要继续将项目中的某些页面标记为草稿，请迁移到内容集合，并手动过滤掉具有 draft: true frontmatter 属性的页面。

移除：getHeaders()

在 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();

移除：在 getStaticPaths() 中使用 rss

在 Astro v3.0 中，在 getStaticPaths() 中使用已废弃的 rss 助手会抛出一个错误。

Astro v4.0 完全移除了这个助手。

我应该怎么做？

如果你正在使用不受支持的方法生成 RSS 源，你现在必须使用 @astrojs/rss 集成来完成一个完整的 RSS 设置。

移除：小写的 HTTP 方法名

在 Astro v3.0 中，使用小写的 HTTP 请求方法名（get、post、put、all、del）已被废弃。

Astro v4.0 完全移除了对小写名称的支持。所有 HTTP 请求方法现在都必须使用大写字母书写。

我应该怎么做？

如果你正在使用已废弃的小写名称，你现在必须将它们替换为相应的大写形式。

请参阅 v3 迁移指南以获取使用大写 HTTP 请求方法的指导。

移除：缺少 base 前缀时的 301 重定向

在 Astro v3.x 中，当访问没有 `base` 路径的 `public` 目录资源时，Astro 预览服务器会返回一个 301 重定向。

Astro v4.0 在预览服务器运行时，对于没有 `base` 路径前缀的 `public` 目录资源会返回 404 状态，这与开发服务器的行为一致。

我应该怎么做？

当使用 Astro 预览服务器时，你所有的静态资源导入和来自 `public` 目录的 URL 都必须在路径前加上`base` 值。

下面的例子展示了当配置了 base: '/docs' 时，要显示 `public` 文件夹中的图片所需的 src 属性

src/pages/index.astro

// To access public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">

移除：astro/client-image 自动转换

在 Astro v3.x 中，astro/client-image 类型（用于已废弃的图像集成）被移除了，但如果在你的 env.d.ts 文件中找到，它会自动转换为默认的 Astro 类型 astro/client。

Astro v4.0 会忽略 astro/client-image，并且不再为你自动更新 env.d.ts。

我应该怎么做？

如果你在 src/env.d.ts 中为 @astrojs/image 配置了类型，并且升级到 v3.0 没有自动为你转换类型，请手动将 astro/client-image 类型替换为 astro/client。

src/env.d.ts

  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />

社区资源

知道有关 Astro v4.0 的好资源吗？编辑此页并在下方添加链接！

已知问题

请在 GitHub 上查看 Astro 的 issues，以了解任何已报告的问题，或自己提交问题。