升级到 Astro v4

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

¥This guide will help you migrate from Astro v3 to Astro v4.

需要将旧项目升级到 v3？看看我们的较旧的迁移指南。

¥Need to upgrade an older project to v3? See our older migration guide.

需要查看 v3 文档吗？访问这个旧版本的文档站点（未维护的 v3.6 快照）。

¥Need to see the v3 docs? Visit this older version of the docs site (unmaintained v3.6 snapshot).

升级 Astro

¥Upgrade Astro

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

¥Update your project’s version of Astro and all official integrations to the latest versions using your package manager.

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

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

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

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

¥You can also upgrade your Astro integrations manually if needed, and you may also need to upgrade other dependencies in your project.

Astro v4.0 包括潜在的重大变化以及删除一些以前弃用的功能。

¥Astro v4.0 includes potentially breaking changes, as well as the removal of some previously deprecated features.

如果你的项目在升级到 v4.0 后未按预期工作，请查看本指南以了解所有重大更改的概述以及有关如何更新代码库的说明。

¥If your project doesn’t work as expected after upgrading to v4.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase.

请参阅变更日志了解完整的发行说明。

¥See the changelog for full release notes.

Astro v4.0 实验标志已删除

¥Astro v4.0 Experimental Flags Removed

删除 devOverlay 实验标志并将任何 i18n 配置移至 astro.config.mjs 中的顶层：

¥Remove the devOverlay experimental flag and move any i18n config to the top level in 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 中提供。

¥These configurations, i18n and the renamed devToolbar, are now available in Astro v4.0.

详细了解这两个令人兴奋的功能以及 v4.0 博客文章中的更多内容！

¥Read more about these two exciting features and more in the v4.0 Blog post!

升级

¥Upgrades

对 Astro 依赖的任何重大升级都可能会导致项目发生重大变化。

¥Any major upgrades to Astro’s dependencies may cause breaking changes in your project.

升级：Vite 5.0

¥Upgraded: Vite 5.0

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

¥In Astro v3.0, Vite 4 was used as the development server and production bundler.

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

¥Astro v4.0 upgrades from Vite 4 to Vite 5.

我应该怎么办？

¥What should I do?

如果你正在使用 Vite 特定的插件、配置或 API，请检查 Vite 迁移指南的重大更改并根据需要升级你的项目。Astro 本身没有重大变化。

¥If you are using Vite-specific plugins, configuration, or APIs, check the Vite migration guide for their breaking changes and upgrade your project as needed. There are no breaking changes to Astro itself.

升级：unified、remark 和 rehype 依赖

¥Upgraded: unified, remark, and rehype dependencies

在 Astro v3.x 中，使用统一的 v10 及其相关兼容的 remark/rehype 包来处理 Markdown 和 MDX。

¥In Astro v3.x, unified v10 and its related compatible remark/rehype packages were used to process Markdown and MDX.

Astro v4.0 将统一到 v11 和其他 remark/rehype 包升级到最新版本。

¥Astro v4.0 upgrades unified to v11 and the other remark/rehype packages to the latest version.

我应该怎么办？

¥What should I do?

如果你使用自定义 remark/rehype 包，请使用包管理器将它们全部更新到最新版本，以确保它们支持统一的 v11。你使用的软件包可以在 astro.config.mjs 中找到。

¥If you used custom remark/rehype packages, update all of them to the latest version using your package manager to ensure they support unified v11. The packages you are using can be found in astro.config.mjs.

如果你使用主动更新的软件包，则不应有任何重大的重大更改，但某些软件包可能尚未与统一 v11 兼容。在部署之前目视检查你的 Markdown/MDX 页面，以确保你的网站按预期运行。

¥There should not be any significant breaking changes if you use actively updated packages, but some packages may not yet be compatible with unified v11. Visually inspect your Markdown/MDX pages before deploying to ensure your site is functioning as intended.

重大变化

¥Breaking Changes

以下更改被视为 Astro 中的重大更改。重大更改可能会或可能不会提供临时向后兼容性，并且所有文档都会更新为仅引用当前支持的代码。

¥The following changes are considered breaking changes in Astro. Breaking changes may or may not provide temporary backwards compatibility, and all documentation is updated to refer to only the current, supported code.

如果需要参考 v3.x 项目的文档，可以浏览这个（未维护）v4.0 发布之前的文档快照项目的文档。

¥If you need to refer to the documentation for a v3.x project, you can browse this (unmaintained) snapshot of the docs from before v4.0 was released.

已重命名：`entrypoint`（集成 API）

¥Renamed: entrypoint (Integrations API)

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

¥In Astro v3.x, the property of the injectRoute integrations API that specified the route entry point was named entryPoint.

Astro v4.0 将此属性重命名为 entrypoint，以便与其他 Astro API 保持一致。entryPoint 属性已弃用，但仍将继续工作并记录警告，提示你更新代码。

¥Astro v4.0 renames this property to entrypoint to be consistent with other Astro APIs. The entryPoint property is deprecated but will continue to work and logs a warning prompting you to update your code.

我应该怎么办？

¥What should I do?

如果你有使用 injectRoute API 的集成，请将 entryPoint 属性重命名为 entrypoint。如果你是库作者，想要同时支持 Astro 3 和 4，则可以同时指定 entryPoint 和 entrypoint，在这种情况下，将不会记录警告。

¥If you have integrations that use the injectRoute API, rename the entryPoint property to entrypoint. If you’re a library author who wants to support both Astro 3 and 4, you can specify both entryPoint and entrypoint, in which case, a warning will not be logged.

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

改变：集成 API 中的 `app.render` 签名

¥Changed: app.render signature in Integrations API

在 Astro v3.0 中，app.render() 方法接受 routeData 和 locals 作为单独的可选参数。

¥In Astro v3.0, the app.render() method accepted routeData and locals as separate, optional arguments.

Astro v4.0 更改了 app.render() 签名。这两个属性现在可在单个对象中使用。对象和这两个属性仍然是可选的。

¥Astro v4.0 changes the app.render() signature. These two properties are now available in a single object. Both the object and these two properties are still optional.

我应该怎么办？

¥What should I do?

如果你正在维护适配器，则当前签名将继续有效，直到下一个主要版本。要迁移到新签名，请将 routeData 和 locals 作为对象的属性而不是作为多个独立参数传递。

¥If you are maintaining an adapter, the current signature will continue to work until the next major version. To migrate to the new signature, pass routeData and locals as properties of an object instead of as multiple independent arguments.

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

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

¥Changed: adapters must now specify supported features

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

¥In Astro v3.x, adapters were not required to specify the features they support.

Astro v4.0 要求适配器传递 supportedAstroFeatures{} 属性来指定它们支持的功能列表。该属性不再是可选的。

¥Astro v4.0 requires adapters to pass the supportedAstroFeatures{} property to specify a list of features they support. This property is no longer optional.

我应该怎么办？

¥What should I do?

适配器作者需要传递 supportedAstroFeatures{} 选项来指定他们支持的功能列表。

¥Adapter authors need to pass the supportedAstroFeatures{} option to specify a list of features they support.

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` 属性

¥Removed: Shiki language path property

在 Astro v3.x 中，传递给 markdown.shikiConfig.langs 的 Shiki 语言会自动转换为 Shikiji 兼容的语言。Shikiji 是 Astro 用于语法高亮显示的内部工具。

¥In Astro v3.x, a Shiki language passed to markdown.shikiConfig.langs was automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting.

Astro v4.0 删除了对 Shiki 语言的 path 属性的支持，该属性配置起来很混乱。它被替换为可以直接传递到 langs 的导入。

¥Astro v4.0 removes support for the path property of a Shiki language, which was confusing to configure. It is replaced by an import which can be passed to langs directly.

我应该怎么办？

¥What should I do?

应导入语言 JSON 文件并将其传递给选项。

¥The language JSON file should be imported and passed to the option instead.

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

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

已弃用

¥Deprecated

以下已弃用的功能不再受支持且不再记录。请相应地更新你的项目。

¥The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly.

某些已弃用的功能可能会暂时继续运行，直到完全删除。其他人可能会默默地没有任何效果，或者抛出错误提示你更新代码。

¥Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code.

已弃用：用于 View Transitions `submit` 事件的 `handleForms`

¥Deprecated: handleForms for View Transitions submit events

在 Astro v3.x 中，使用 <ViewTransitions /> 组件的项目需要选择处理 form 元素的 submit 事件。这是通过传递 handleForms 属性来完成的。

¥In Astro v3.x, projects using the <ViewTransitions /> component were required to opt-in to handling submit events for form elements. This was done by passing a handleForms prop.

当使用 <ViewTransitions /> 时，Astro v4.0 默认处理 form 元素的 submit 事件。handleForms 属性已被弃用，不再有任何作用。

¥Astro v4.0 handles submit events for form elements by default when <ViewTransitions /> are used. The handleForms prop has been deprecated and no longer has any effect.

我应该怎么办？

¥What should I do?

从 ViewTransitions 组件中删除 handleForms 属性。不再需要了。

¥Remove the handleForms property from your ViewTransitions component. It is no longer necessary.

---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- stuff here -->
  </body>
</html>

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

¥To opt out of submit event handling, add the data-astro-reload attribute to relevant form elements.

<form action="/contact" data-astro-reload>
  <!-- -->
</form>

以前弃用的功能现已删除

¥Previously deprecated features now removed

以下已弃用的功能现已从代码库中完全删除，无法再使用。即使在弃用后，其中一些功能可能仍会继续在你的项目中发挥作用。其他人可能默默地没有任何影响。

¥The following deprecated features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect.

现在包含这些已删除功能的项目将无法构建，并且将不再有任何支持文档提示你删除这些功能。

¥Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features.

已删除：返回简单来自端点的对象

¥Removed: returning simple objects from endpoints

在 Astro v3.x 中，不推荐从端点返回简单对象，但仍然支持以保持与 Astro v2 的兼容性。还提供了 ResponseWithEncoding 实用程序来简化迁移。

¥In Astro v3.x, returning simple objects from endpoints was deprecated, but was still supported to maintain compatibility with Astro v2. A ResponseWithEncoding utility was also provided to ease the migration.

Astro v4.0 取消了对简单对象的支持，并要求端点始终返回 Response。ResponseWithEncoding 实用程序也被删除，以支持适当的 Response 类型。

¥Astro v4.0 removes support for simple objects and requires endpoints to always return a Response. The ResponseWithEncoding utility is also removed in favor of a proper Response type.

我应该怎么办？

¥What should I do?

更新你的端点以直接返回 Response 对象。

¥Update your endpoints to return a Response object directly.

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

要删除 ResponseWithEncoding 的使用，请重构代码以使用 ArrayBuffer 代替：

¥To remove usage of ResponseWithEncoding, refactor your code to use an ArrayBuffer instead:

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`

¥Removed: build.split and build.excludeMiddleware

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

¥In Astro v3.0, build.split and build.excludeMiddleware build config options were deprecated and replaced with adapter configuration options to perform the same tasks.

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

¥Astro v4.0 removes these properties entirely.

我应该怎么办？

¥What should I do?

如果你使用的是已弃用的 build.split 或 build.excludeMiddleware，则现在必须将其删除，因为它们已不再存在。

¥If you are using the deprecated build.split or build.excludeMiddleware, you must now remove them as these no longer exist.

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

¥Please see the v3 migration guide to update these deprecated middleware properties with adapter configurations.

已删除：`Astro.request.params`

¥Removed: Astro.request.params

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

¥In Astro v3.0, the Astro.request.params API was deprecated, but preserved for backwards compatibility.

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

¥Astro v4.0 removes this option entirely.

我应该怎么办？

¥What should I do?

将所有匹配项更新为 Astro.params，这是受支持的替换。

¥Update all occurrences to Astro.params, which is the supported replacement.

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

已删除：`markdown.drafts`

¥Removed: markdown.drafts

在 Astro v3.0 中，不推荐使用 markdown.drafts 来控制草稿帖子的构建。

¥In Astro v3.0, using markdown.drafts to control the building of draft posts was deprecated.

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

¥Astro v4.0 removes this option entirely.

我应该怎么办？

¥What should I do?

如果你使用的是已弃用的 markdown.drafts，你现在必须将其删除，因为它不再存在。

¥If you are using the deprecated markdown.drafts, you must now remove it as it no longer exists.

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

¥To continue to mark some pages in your project as drafts, migrate to content collections and manually filter out pages with the draft: true frontmatter property instead.

已删除：`getHeaders()`

¥Removed: getHeaders()

在 Astro v3.0 中，getHeaders() Markdown 导出已被弃用并替换为 getHeadings()。

¥In Astro v3.0, the getHeaders() Markdown export was deprecated and replaced with getHeadings().

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

¥Astro v4.0 removes this option entirely.

我应该怎么办？

¥What should I do?

如果你使用的是已弃用的 getHeaders()，你现在必须将其删除，因为它不再存在。将任何实例替换为 getHeadings()，这是受支持的替换。

¥If you are using the deprecated getHeaders(), you must now remove it as it no longer exists. Replace any instances with getHeadings(), which is the supported replacement.

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

已删除：在 `getStaticPaths()` 中使用 `rss`

¥Removed: using rss in getStaticPaths()

在 Astro v3.0 中，在 getStaticPaths() 中使用已弃用的 rss 助手会引发错误。

¥In Astro v3.0, using the deprecated rss helper in getStaticPaths() would throw an error.

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

¥Astro v4.0 removes this helper entirely.

我应该怎么办？

¥What should I do?

如果你使用不受支持的方法来生成 RSS 源，则现在必须使用 @astrojs/rss 整合进行完整的 RSS 设置。

¥If you are using the unsupported method for generating RSS feeds, you must now use the @astrojs/rss integration for a complete RSS setup.

已删除：小写 HTTP 方法名称

¥Removed: lowercase HTTP method names

在 Astro v3.0 中，不推荐使用小写 HTTP 请求方法名称（get、post、put、all、del）。

¥In Astro v3.0, using lowercase HTTP request method names (get, post, put, all, del) was deprecated.

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

¥Astro v4.0 removes support for lowercase names entirely. All HTTP request methods must now be written using uppercase.

我应该怎么办？

¥What should I do?

如果你使用的是已弃用的小写名称，则现在必须将其替换为相应的大写名称。

¥If you are using the deprecated lowercase names, you must now replace them with their uppercase equivalents.

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

¥Please see the v3 migration guide for guidance using uppercase HTTP request methods.

已删除：缺少 `base` 前缀时进行 301 重定向

¥Removed: 301 redirects when missing a base prefix

在 Astro v3.x 中，Astro 预览服务器在没有基本路径的情况下访问公共目录资源时返回 301 重定向。

¥In Astro v3.x, the Astro preview server returned a 301 redirect when accessing public directory assets without a base path.

当预览服务器运行时，Astro v4.0 返回没有公共目录资源基本路径前缀的 404 状态，与开发服务器的行为相匹配。

¥Astro v4.0 returns a 404 status without a base path prefix for public directory assets when the preview server is running, matching the behavior of the dev server.

我应该怎么办？

¥What should I do?

使用 Astro 预览服务器时，公共目录中的所有静态资源导入和 URL 都必须在路径中添加基值前缀。

¥When using the Astro preview server, all of your static asset imports and URLs from the public directory must have the base value prefixed to the path.

以下示例显示了配置 base: '/docs' 时显示公用文件夹中的图片所需的 src 属性：

¥The following example shows the src attribute required to display an image from the public folder when base: '/docs' is configured:

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

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

已删除：`astro/client-image` 自动转换

¥Removed: astro/client-image auto-conversion

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

¥In Astro v3.x, the astro/client-image type (used for the deprecated image integration) was removed but was auto-converted to the default Astro type astro/client if found in your env.d.ts file.

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

¥Astro v4.0 ignores astro/client-image and will no longer update env.d.ts for you automatically.

我应该怎么办？

¥What should I do?

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

¥If you had types configured for @astrojs/image in src/env.d.ts and upgrading to v3.0 did not automatically convert the type for you, replace the astro/client-image type manually with astro/client.

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

社区资源

¥Community Resources

知道 Astro v4.0 的好资源吗？编辑这个页面并在下面添加链接！

¥Know a good resource for Astro v4.0? Edit this page and add a link below!

已知的问题

¥Known Issues

请检查 GitHub 上的 Astro 问题是否有任何报告的问题，或自行提交问题。

¥Please check Astro’s issues on GitHub for any reported issues, or to file an issue yourself.

升级到 Astro v4

升级 Astro

Astro v4.0 实验标志已删除

升级

升级：Vite 5.0

我应该怎么办？

升级：unified、remark 和 rehype 依赖

我应该怎么办？

重大变化

已重命名：entrypoint（集成 API）

我应该怎么办？

改变：集成 API 中的 app.render 签名

我应该怎么办？

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

我应该怎么办？

已删除：Shiki 语言 path 属性

我应该怎么办？

已弃用

已弃用：用于 View Transitions submit 事件的 handleForms

我应该怎么办？

以前弃用的功能现已删除

已删除：返回简单来自端点的对象

我应该怎么办？

已删除：build.split 和 build.excludeMiddleware

我应该怎么办？

已删除：Astro.request.params

我应该怎么办？

已删除：markdown.drafts

我应该怎么办？

已删除：getHeaders()

我应该怎么办？

已删除：在 getStaticPaths() 中使用 rss

我应该怎么办？

已删除：小写 HTTP 方法名称

我应该怎么办？

已删除：缺少 base 前缀时进行 301 重定向

我应该怎么办？

已删除：astro/client-image 自动转换

我应该怎么办？

社区资源

已知的问题

已重命名：`entrypoint`（集成 API）

改变：集成 API 中的 `app.render` 签名

已删除：Shiki 语言 `path` 属性

已弃用：用于 View Transitions `submit` 事件的 `handleForms`

已删除：`build.split` 和 `build.excludeMiddleware`

已删除：`Astro.request.params`

已删除：`markdown.drafts`

已删除：`getHeaders()`

已删除：在 `getStaticPaths()` 中使用 `rss`

已删除：缺少 `base` 前缀时进行 301 重定向

已删除：`astro/client-image` 自动转换