diff --git a/src/content/docs/zh-cn/guides/upgrade-to/v6.mdx b/src/content/docs/zh-cn/guides/upgrade-to/v6.mdx
new file mode 100644
index 0000000000000..b166634a3bb14
--- /dev/null
+++ b/src/content/docs/zh-cn/guides/upgrade-to/v6.mdx
@@ -0,0 +1,1767 @@
+---
+title: 升级到 Astro v6
+description: 如何将你的项目升级到 Astro v6.0。
+sidebar:
+ label: v6.0
+i18nReady: true
+---
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
+import { Steps } from '@astrojs/starlight/components';
+import ReadMore from '~/components/ReadMore.astro'
+import SourcePR from '~/components/SourcePR.astro'
+
+本指南将帮助你从 Astro v5 迁移到 Astro v6。
+
+需要将旧项目升级到 v5 吗？请参阅我们的 [旧版本迁移指南](/zh-cn/guides/upgrade-to/v5/)。
+
+需要查阅 v5 的文档？请访问这个[旧版本文档站 (不被维护的 v5.18.0 快照)](https://v5.docs.astro.build/)。
+
+## 升级 Astro
+
+使用你的包管理器将项目的 Astro 版本更新到最新版本：
+
+
+
+ ```shell
+ # 同时升级 Astro 和官方集成
+ npx @astrojs/upgrade
+ ```
+
+
+ ```shell
+ # 同时升级 Astro 和官方集成
+ pnpm dlx @astrojs/upgrade
+ ```
+
+
+ ```shell
+ # 同时升级 Astro 和官方集成
+ yarn dlx @astrojs/upgrade
+ ```
+
+
+
+如果需要的话，你也可以 [手动升级 Astro 集成](/zh-cn/guides/integrations-guide/#手动更新)，你可能还需要升级项目中的其他依赖。
+
+:::note[需要继续吗？]
+升级 Astro 后，你可能不需要对你的项目做任何更改！
+
+但是，如果你遇到错误或意外的行为，请查看下面的内容，了解有哪些变化可能需要在你的项目中更新。
+:::
+
+Astro v6.0 包含了 [潜在的破坏性变更](#破坏性变更)，以及对于功能的一些移除和弃用。
+
+如果你的项目在升级到 v6.0 后的行为不符合预期，请参考本指南，了解所有破坏性变更的概述以及如何修改你的代码的说明。
+
+完整的发行说明请参阅 [Astro changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md)。
+
+## 依赖升级
+
+对 Astro 依赖项的任何重大升级都可能导致你的项目发生破坏性变更。
+
+### Node 22
+
+
+
+Node 18 已于 2025 年 3 月结束生命周期，Node 20 计划于 2026 年 4 月结束生命周期。
+
+Astro v6.0 完全放弃对 Node 18 和 Node 20 的支持，以便所有 Astro 用户都能利用 Node 更现代的特性。
+
+#### 我应该做什么？
+
+检查你的开发环境和部署环境是否都在使用 **Node `22.12.0` 或更高版本**。
+
+
+1. 使用以下命令检查本地的 Node 版本：
+
+ ```sh
+ node -v
+ ```
+
+2. 检查你的 [部署环境](/zh-cn/guides/deploy/) 的文档，确认它们支持 Node 22。
+
+ 你可以通过仪表板配置设置或 `.nvmrc` 文件为你的 Astro 项目指定 Node `22.12.0`。
+
+ ```bash title=".nvmrc"
+ 22.12.0
+ ```
+
+
+### Vite 7.0
+
+
+
+Astro v6.0 已升级到 Vite v7.0 作为开发服务器和生产打包工具。
+
+#### 我应该做什么？
+
+如果你正在使用 Vite 特定的插件、配置或 API，请查看 [Vite 迁移指南](https://vite.dev/guide/migration) 中的破坏性变更，并根据需要升级你的项目。
+
+使用 [Astro 的 `getViteConfig()` 辅助函数](/zh-cn/guides/testing/#vitest) 需要至少 Vitest v3.2 或 v4.1 beta 5。
+
+### Vite Environment API
+
+
+
+Astro v6.0 在内部重构使用 [Vite 新的 Environments API](https://vite.dev/guide/api-environment) 后，对 Astro 管理不同运行时环境（客户端、服务器和预渲染）的方式进行了重大更改。
+
+#### 我应该做什么？
+
+集成和适配器的维护者应特别关注影响 Integration API 和 Adapter API 这些部分的更改（完整的详细信息包含在下面这些 API 的其他破坏性变更说明中）：
+
+- [Rollup 输出文件名配置路径](#变更rollup-输出文件名配置路径vite-配置)
+- [集成钩子和 HMR 访问模式](#变更集成钩子和-hmr-访问模式集成-api)
+- [`SSRManifest` 结构](#变更ssrmanifest-接口结构适配器-api)
+- [使用 `RouteData` 生成路由](#已移除routedatagenerate适配器-api)
+- [包含百分号编码的百分号路由（例如 `%25`）](#已移除路由中的百分号编码)
+- [`astro:ssr-manifest` 虚拟模块](#已移除astrossr-manifest-虚拟模块集成-api)
+- [`astro/app/node` 中的 `NodeApp`](#已弃用astroappnode-中的-nodeapp适配器-api)
+- [`astro/app/node` 中的 `loadManifest()` 和 `loadApp()`](#已弃用astroappnode-中的-loadmanifest-和-loadapp适配器-api)
+- [`createExports()` 和 `start()`](#已弃用createexports-和-start适配器-api)
+
+### Zod 4
+
+Astro v6.0 升级到 Zod 4，这是一个主要依赖更新，可能需要更改项目中的自定义 Zod schema。
+
+#### 我应该做什么？
+
+如果你在 `content.config.ts` 或其他配置文件中有自定义 Zod schema，你需要为 Zod 4 更新它们。请参阅 [Zod 迁移指南](https://zod.dev/v4/changelog) 了解 Zod API 的详细更改。
+
+值得注意的是，[许多 `string()` 格式已被弃用](https://zod.dev/v4/changelog#deprecates-email-etc)（例如 `z.string().email()`、`z.string.url()`），它们的 API 已移至顶级 `z` 命名空间。你可能需要更新 Astro Actions 的表单输入验证方式：
+
+```ts title="src/actions/index.ts" ins={2} del={1}
+email: z.string().email(),
+email: z.email(),
+```
+
+此外，Zod 对 [错误消息处理进行了一些更改](https://zod.dev/v4/changelog#error-customization)，并放弃了对自定义 `errorsMap` 的支持，该功能曾用于重新定义或翻译错误消息。你可能需要更新你的自定义错误消息：
+
+```ts title="src/actions/index.ts" ins={2} del={1}
+z.string().min(5, { message: "Too short." });
+z.string().min(5, { error: "Too short." });
+```
+
+另外，如果你使用 [带转换的 `.default()`](https://zod.dev/v4/changelog#default-updates)，你可能需要更新你的 schema。在 Zod 4 中，默认值必须匹配输出类型（转换后），而不是输入类型。当输入为 `undefined` 时，默认值会短路解析：
+
+```ts title="src/content.config.ts" del={5-6} ins={7-8}
+import { z } from 'astro/zod';
+
+const blog = defineCollection({
+ schema: z.object({
+ // Zod 3: 默认值匹配输入类型（字符串）
+ views: z.string().transform(Number).default("0"),
+ // Zod 4: 默认值必须匹配输出类型（数字）
+ views: z.string().transform(Number).default(0),
+ })
+});
+```
+
+如果需要旧行为（默认值会被解析），请使用新的 `.prefault()` 方法。
+
+这些只是从 Zod 3 升级到 Zod 4 的众多更改中的一部分。如果你在升级到 Astro 6 后遇到 Zod schema 的任何问题，请查阅 [Zod 4 更新日志](https://zod.dev/v4/changelog) 获取完整的升级指导。
+
+此外，还有一个[社区 codemod](https://github.com/nicoespeon/zod-v3-to-v4)，可以在从 Zod 3 迁移到 Zod 4 时自动执行其中一些更改。
+
+你可以通过 [从 `astro/zod` 导入 Zod](#已弃用astrocontent-中的-astroschema-和-z) 来确保使用与 Astro 内部相同的 Zod 版本。
+
+```ts
+import { z } from 'astro/zod';
+```
+
+了解更多关于 [`astro/zod` 模块](/zh-cn/reference/modules/astro-zod/)。
+
+### Shiki 4.0
+
+
+
+Astro v6.0 的语法高亮工具已升级到 Shiki v4.0。
+
+#### 我应该做什么？
+
+如果你正在使用 Shiki 特定的 API，请查看 [Shiki 迁移指南](https://shiki.style/blog/v4) 中的破坏性变更，并根据需要升级你的项目。
+
+### 官方 Astro 集成
+
+所有 [Astro 官方服务器适配器](/zh-cn/guides/on-demand-rendering/#服务器适配器) 也已更新到新的主要版本，以配合升级到 Vite v7.0 和 Vite 的 Environment API 作为开发服务器和生产打包工具。
+
+值得一提的是，Astro 的 Cloudflare 适配器经过了重大更改，预计会对现有的 Cloudflare 设置产生破坏性变更。
+
+请参阅 [Cloudflare 适配器升级说明](/zh-cn/guides/integrations-guide/cloudflare/#upgrading-to-v13-and-astro-6) 获取详细的迁移指导。
+
+#### 我应该做什么？
+
+如果你正在使用 Astro 适配器进行按需渲染或其他平台特定功能，请检查你的特定适配器的更新日志获取升级指导：
+
+- [`@astrojs/cloudflare` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/cloudflare/CHANGELOG.md)
+- [`@astrojs/netlify` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/netlify/CHANGELOG.md)
+- [`@astrojs/node` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/node/CHANGELOG.md)
+- [`@astrojs/vercel` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/vercel/CHANGELOG.md)
+
+## 旧版
+
+以下的功能现在被认为是旧版功能。它们应该可以正常运行，但不再推荐使用它们，并且它们处于维护模式。它们不会在未来得到改进，也不会更新文档。这些功能最终将被弃用，然后完全删除。
+
+### 旧版：内容集合向后兼容性
+
+在 Astro 5.x 中，项目可以延迟升级到为内容集合引入的新 Content Layer API，因为存在一些之前没有在标志后面的自动向后兼容性。这意味着即使你没有启用 `legacy.collections` 标志，也可以从 Astro 4 升级到 Astro 5 而不需要更新内容集合。项目会继续构建，不会显示任何错误或警告。
+
+Astro v6.0 移除了这种自动的旧版内容集合支持，以及 [`legacy.collections` 标志](#已移除旧版内容集合)。所有内容集合现在必须使用 [Astro v5.0 中引入的 Content Layer API](https://astro.build/blog/content-layer-deep-dive/)，它为所有内容集合提供支持。**不提供向后兼容性支持。**
+
+#### 我应该做什么？
+
+如果你在更新到 v6 后遇到内容集合错误，请[检查项目中是否有任何需要更新到 Content Layer API 的已移除旧版功能](#如果你有)。
+
+请参阅 [Astro v5 升级指南](/zh-cn/guides/upgrade-to/v5/#旧版v20-内容集合-api) 获取将旧版集合升级到新 Content Layer API 的详细说明。
+
+如果你无法立即更新，可以启用 [`legacy.collectionsBackwardsCompat` 标志](/zh-cn/reference/legacy-flags/#集合) 作为临时迁移辅助：
+
+```js title="astro.config.mjs"
+export default defineConfig({
+ legacy: {
+ collectionsBackwardsCompat: true,
+ },
+});
+```
+
+此标志保留一些旧版 v4 内容集合功能：
+
+- 支持旧版配置文件 `src/content/config.ts`
+- 支持 `type: 'content'` 和 `type: 'data'` 而无需 loader
+- 保留旧版条目 API：`entry.slug` 和 `entry.render()`
+- 使用基于路径的条目 ID 而不是基于 slug 的 ID
+
+**这是一个临时迁移辅助工具。** 请尽快将你的集合迁移到 Content Layer API，然后禁用此标志。
+
+## 已弃用
+
+以下弃用的功能已不再被支持，也不会再被文档记录。请相应地更新你的项目。
+
+一些已弃用的功能可能会继续工作一段时间，直到它们被完全移除。其他功能可能会失去作用，或抛出错误提示你更新代码。
+
+### 已弃用：`getStaticPaths()` 中的 `Astro`
+
+
+
+在 Astro 5.x 中，可以在 `getStaticPaths()` 内部访问 `Astro` 对象。然而，尽管它的类型与 frontmatter 中可访问的 `Astro` 对象相同，但这个对象只有 `site` 和 `generator` 属性。这可能导致用户对 `getStaticPaths()` 中哪些 `Astro` 对象属性可用造成混淆。
+
+Astro 6.0 弃用了 `getStaticPaths()` 中的这个对象以避免混淆，并改进了尝试访问不可用的 `Astro` 值时的错误处理。在 `getStaticPaths()` 中使用 `Astro.site` 或 `Astro.generator` 现在会记录弃用警告，访问任何其他属性将抛出带有帮助信息的特定错误。在未来的主要版本中，此对象将被完全移除，访问 `Astro.site` 或 `Astro.generator` 也会抛出错误。
+
+#### 我应该做什么？
+
+如果你在 `getStaticPaths()` 函数作用域内尝试访问任何 `Astro` 属性，请更新你的函数。完全移除 `Astro.generator`，并将所有 `Astro.site` 的出现替换为 `import.meta.env.SITE`：
+
+```astro title="src/pages/blog/[slug].astro" del={5,6} ins={7}
+---
+import { getPages } from "../../../utils/data";
+
+export async function getStaticPaths() {
+ console.log(Astro.generator);
+ return getPages(Astro.site);
+ return getPages(import.meta.env.SITE);
+}
+---
+```
+
+了解更多关于 [内置环境变量如 `import.meta.env.SITE`](/zh-cn/guides/environment-variables/#默认环境变量)，它们在 [使用 `getStaticPaths()` 动态生成静态路由](/zh-cn/guides/routing/#静态-ssg-模式) 时可访问。
+
+### 已弃用：`import.meta.env.ASSETS_PREFIX`
+
+
+
+在 Astro 5.x 中，可以通过内置环境变量 `import.meta.env.ASSETS_PREFIX` 在 Astro 配置中访问 `build.assetsPrefix`。然而，Astro v5.7.0 引入了 `astro:config` 虚拟模块，暴露了 Astro 配置的非穷尽、可序列化、类型安全版本，其中包括直接访问 `build.assetsPrefix`。这成为访问 Astro 生成的资源链接前缀的首选方式，尽管环境变量仍然存在。
+
+Astro 6.0 弃用此变量，推荐使用 `astro:config/server` 模块中的 `build.assetsPrefix`。
+
+#### 我应该做什么？
+
+将所有 `import.meta.env.ASSETS_PREFIX` 的出现替换为从 `astro:config/server` 导入的 `build.assetsPrefix`。这是一个直接替换，提供现有值，你的代码不需要其他更改：
+
+```ts del={4} ins={2,5}
+import { someLogic } from "./utils"
+import { build } from "astro:config/server"
+
+someLogic(import.meta.env.ASSETS_PREFIX)
+someLogic(build.assetsPrefix)
+```
+
+了解更多关于 [`astro:config` 虚拟模块](/zh-cn/reference/modules/astro-config/)。
+
+### 已弃用：`astro:content` 中的 `astro:schema` 和 `z`
+
+
+
+在 Astro 5.x 中，`astro:schema` 被引入作为 `astro/zod` 的别名。`z` 也从 `astro:content` 导出以方便使用。然而，这偶尔会让用户感到困惑，不确定应该从哪里导入。
+
+Astro 6.0 弃用 `astro:schema` 和 `astro:content` 中的 `z`，推荐使用 `astro/zod`。
+
+#### 我应该做什么？
+
+将所有 `astro:schema` 的出现替换为 `astro/zod`：
+
+```ts del={1} ins={2}
+import { z } from "astro:schema"
+import { z } from "astro/zod"
+```
+
+从你的 `astro:content` 导入中移除 `z`，改为从 `astro/zod` 单独导入 `z`：
+
+```ts title="src/content.config.ts" del={1} ins={2-3}
+import { defineCollection, z } from "astro:content"
+import { defineCollection } from "astro:content"
+import { z } from "astro/zod"
+```
+
+了解更多关于 [使用 Zod 定义集合 schema](/zh-cn/guides/content-collections/#使用-zod-定义数据类型)。
+
+### 已弃用：暴露的 `astro:transitions` 内部实现
+
+
+
+在 Astro 5.x 中，一些内部实现从 `astro:transitions` 和 `astro:transitions/client` 导出，但这些本意不是为公共使用而暴露的。
+
+Astro 6.0 移除了以下函数和类型作为 `astro:transitions` 和 `astro:transitions/client` 虚拟模块的导出。这些不能再在你的项目文件中导入：
+
+- `createAnimationScope()`
+- `isTransitionBeforePreparationEvent()`
+- `isTransitionBeforeSwapEvent()`
+- `TRANSITION_BEFORE_PREPARATION`
+- `TRANSITION_AFTER_PREPARATION`
+- `TRANSITION_BEFORE_SWAP`
+- `TRANSITION_AFTER_SWAP`
+- `TRANSITION_PAGE_LOAD`
+
+#### 我应该做什么？
+
+移除所有 `createAnimationScope()` 的出现：
+
+```ts del={1}
+import { createAnimationScope } from 'astro:transitions';
+```
+
+更新其他已弃用导出的所有出现：
+
+```ts del={1-4,6,9} ins={7,10}
+import {
+ isTransitionBeforePreparationEvent,
+ TRANSITION_AFTER_SWAP,
+} from 'astro:transitions/client';
+
+console.log(isTransitionBeforePreparationEvent(event));
+console.log(event.type === 'astro:before-preparation');
+
+console.log(TRANSITION_AFTER_SWAP);
+console.log('astro:after-swap');
+```
+
+了解更多关于 [View Transitions Router API 参考](/zh-cn/reference/modules/astro-transitions/) 中所有可用的工具。
+
+### 已弃用：session driver 字符串签名
+
+
+
+在 Astro 5.x 中，可以提供任何 [unstorage provider](https://unstorage.unjs.io/drivers) 名称或自定义入口点来定义 session driver，选项也直接提供给 `session` 配置。然而，我们觉得这个 API 受限且与 Astro 配置的其他部分不一致。
+
+Astro 6.0 弃用 driver 字符串签名和选项，推荐使用新的对象形式。
+
+#### 我应该做什么？
+
+更新你的 session 配置以使用新导出的 `sessionDrivers`：
+
+```js title="astro.config.mjs" del={1,6-9} ins={2,10-12}
+import { defineConfig } from 'astro/config'
+import { defineConfig, sessionDrivers } from 'astro/config'
+
+export default defineConfig({
+ session: {
+ driver: 'redis',
+ options: {
+ url: process.env.REDIS_URL
+ },
+ driver: sessionDrivers.redis({
+ url: process.env.REDIS_URL
+ }),
+ cookie: {
+ secure: true
+ },
+ ttl: 3600
+ }
+})
+```
+
+了解更多关于 [可用的 session driver](/zh-cn/reference/session-driver-reference/#building-a-session-driver)。
+### 已弃用：`astro/app/node` 中的 `NodeApp`（适配器 API）
+
+
+
+在 Astro 5.x 中，适配器可以使用 `App` 处理标准 web 请求/响应，或使用 `NodeApp` 处理 node 请求/响应来实现其服务器入口点。
+
+Astro 6.0 弃用 `NodeApp`，推荐使用 `createApp()` 和新工具：`createRequest()` 和 `writeResponse()`。这允许更一致的 API，同时保留与以前相同的功能。它还弃用了 `NodeAppHeadersJson` 类型。
+
+#### 我应该做什么？
+
+如果你构建了适配器，请用 `createApp()` 更新所有 `NodeApp` 的使用：
+
+```js title="my-adapter/server.js" del={1-12} ins={13-22}
+import { NodeApp } from 'astro/app/node';
+
+export function createExports(manifest) {
+ const app = new NodeApp(manifest);
+
+ const handler = async (req, res) => {
+ const response = await app.render(req);
+ await NodeApp.writeResponse(response, res);
+ };
+
+ return { handler };
+}
+import { createApp } from 'astro/app/entrypoint';
+import { createRequest, writeResponse } from 'astro/app/node';
+
+const app = createApp();
+
+export const handler = async (req, res) => {
+ const request = createRequest(req);
+ const response = await app.render(request);
+ await writeResponse(response, res);
+}
+```
+
+了解更多关于 [`astro/app/node` 模块](/zh-cn/reference/modules/astro-app/#imports-from-astroappnode)。
+
+### 已弃用：`astro/app/node` 中的 `loadManifest()` 和 `loadApp()`（适配器 API）
+
+
+
+在 Astro 5.x 中，`astro/app/node` 暴露了 `loadManifest()` 和 `loadApp()` 工具，允许从 `URL` 实例加载 SSR manifest 或 `NodeApp` 实例。然而，这些没有被记录，并且不再是 v6 Adapter API 推荐的用法。
+
+Astro 6.0 弃用这两个函数。
+
+#### 我应该做什么？
+
+如果你构建了适配器，移除 `loadManifest()` 并用 `createApp()` 替换 `loadApp()`：
+
+```js title="my-adapter/server.js" del={1-5} ins={6-8}
+import { loadManifest, loadApp, NodeApp } from 'astro/app/node';
+
+const manifest = await loadManifest(new URL(import.meta.url));
+const app1 = new NodeApp(loadManifest);
+const app2 = await loadApp(new URL(import.meta.url));
+import { createApp } from 'astro/app/entrypoint';
+
+const app = createApp();
+```
+
+了解更多关于 [`astro/app/entrypoint` 模块](/zh-cn/reference/modules/astro-app/#imports-from-astroappentrypoint)。
+
+### 已弃用：`createExports()` 和 `start()`（适配器 API）
+
+
+
+在 Astro 5.x 中，适配器必须在服务器入口点中使用 `createExports()` 函数提供主机所需的导出，然后将它们作为 `exports` 列表传递给 `setAdapter()`。
+
+Astro 6.0 引入了一种更简单但更强大的服务器入口点制作方式。这依赖于向 `setAdapter()` 传递新选项 `entrypointResolution: "auto"`。
+
+然而，为了向后兼容现有适配器，`entrypointResolution` 的默认值（`"explicit"`）模仿 Astro 5.x API 行为。这意味着你的适配器可以继续运行，直到你可以完全将适配器迁移到 `auto` 值，如下所示。
+
+请注意，`entrypointResolution: "explicit"`（保持 v5 API 行为）被认为是已弃用的用法，但提供此选项是为了让你不需要立即更改适配器，并允许适配器作者有时间更新。此选项将在未来的主要版本中移除，所有适配器都将使用 `entrypointResolution: "auto"`。
+
+#### 我应该做什么？
+
+如果你是拥有公开仓库的适配器作者，并且在 `package.json` 中 [包含 `astro-adapter` 关键字](/zh-cn/reference/publish-to-npm/#分类)，Astro 核心团队将尝试直接向你的仓库提交 PR 来帮助你迁移代码（如果你尚未遵循以下步骤）。
+
+如果你因为使用尚未更新的社区适配器而看到警告，请直接联系适配器作者告知他们。更新适配器最终是他们的责任。你也可以在我们的 [Discord `#integrations` 频道](https://astro.build/chat) 告知 Astro 核心团队，我们将尝试帮助适配器作者升级。
+
+如果你构建了适配器，请按照以下步骤移除旧版 v5 行为：
+
+
+
+1. 更新你的 `setAdapter()`：设置 `entrypointResolution: "auto"`，移除 `exports` 和 `args`
+
+ ```js title="my-adapter.mjs" ins={3} del={4-5}
+ setAdapter({
+ // ...
+ entrypointResolution: 'auto',
+ exports: ['handler'],
+ args: { assets: config.build.assets }
+ })
+ ```
+
+2. 更新你的服务器入口点以提供任何所需的导出，而不使用 `createExports()`：
+
+ ```js title="my-adapter/server.js" del={1-11} ins={12-18}
+ import { App } from 'astro/app';
+
+ export function createExports(manifest) {
+ const app = new App(manifest);
+
+ const handler = (event, context) => {
+ // ...
+ };
+
+ return { handler };
+ }
+ import { createApp } from 'astro/app/entrypoint';
+
+ const app = createApp();
+
+ export const handler = (event, context) => {
+ // ...
+ }
+ ```
+
+3. 如果你的适配器提供 `start()` 函数，更新你的服务器入口点以直接调用代码：
+
+ ```js title="my-adapter/server.js" del={1-9} ins={10-16}
+ import { App } from 'astro/app';
+
+ export function start(manifest) {
+ const app = new App(manifest);
+
+ addEventListener('fetch', event => {
+ // ...
+ });
+ }
+ import { createApp } from 'astro/app/entrypoint';
+
+ const app = createApp();
+
+ addEventListener('fetch', event => {
+ // ...
+ });
+ ```
+
+4. 如果你依赖 `args`，[创建一个虚拟模块来传递构建时配置](/en/reference/adapter-reference/#passing-build-time-configuration) 并从虚拟模块导入它们：
+
+ ```js title="my-adapter/server.js" del={1-3} ins={4}
+ export function createExports(manifest, { assets }) {
+ // ...
+ }
+ import { assets } from 'virtual:@example/my-adapter:config';
+ ```
+
+
+
+了解更多关于 [适配器 API](/zh-cn/reference/adapter-reference/)。
+
+## 已移除
+
+以下功能已完全从代码库中移除，不能再使用。其中一些功能即使被弃用后可能仍在你的项目中工作。其他功能可能静默无效。
+
+现在包含这些已移除功能的项目将无法构建，并且不再有任何支持文档提示你移除这些功能。
+
+
+### 已移除：旧版内容集合
+
+
+
+在 Astro 5.x 中，仍然可以使用 [Astro v2.0 中首次引入的原始内容集合 API](https://astro.build/blog/introducing-content-collections/)，**通过 `legacy` 配置标志或通过内置的向后兼容性**。这些方法允许你升级到 Astro v5，即使你还没有准备好或无法将现有内容集合更新为由新 Content Layer API 支持的集合。
+
+Astro v6.0 完全移除了这个之前已弃用的内容集合 API 支持，包括 `legacy.collections` 标志**以及一些之前没有在标志后面的内置向后兼容性**。所有内容集合现在必须使用 [Astro v5.0 中引入的 Content Layer API](https://astro.build/blog/content-layer-deep-dive/)。**不提供向后兼容性支持。**
+
+#### 我应该做什么？
+
+如果你之前启用了旧版标志，必须移除它。
+
+```ts title="astro.config.mjs" del={5}
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+ legacy: {
+ collections: true,
+ }
+})
+```
+
+此外，如果你没有为 Astro v5.0 升级集合，请确保你的内容集合已为新 API **完全更新**。
+
+Astro v5.x 包含一些自动向后兼容性，允许内容集合继续工作，即使它们没有更新为使用新 API。因此，你的 v5 集合可能包含一个或多个需要为新 API 更新的旧版功能，即使你的项目之前没有错误。
+
+如果你在升级到 v6 后遇到 [内容集合错误](/zh-cn/reference/error-reference/#内容集合错误) 或警告，请使用以下列表帮助你识别和升级代码中可能存在的任何旧版功能。
+
+##### 如果你有……
+
+
+没有内容集合配置文件
+创建 `src/content.config.ts` 并在其中 [定义你的集合](/en/guides/content-collections/#defining-build-time-content-collections)。
+
+
+
+位于 `src/content/config.ts` 的配置文件 / （[`LegacyContentConfigError`](/zh-cn/reference/errors/legacy-content-config-error/)）
+将此文件重命名并移动到 `src/content.config.ts`
+
+
+
+没有定义 `loader` 的集合 / （[`ContentCollectionMissingALoaderError`](/zh-cn/reference/errors/content-collection-missing-loader/)）
+
+导入 [Astro 内置的 `glob()` loader](/en/guides/content-collections/#the-glob-loader) 并为你的集合条目定义 `pattern` 和 `base`：
+
+```ts ins={4,7}
+// src/content.config.ts
+import { defineCollection } from 'astro:content';
+import { z } from 'astro/zod';
+import { glob } from 'astro/loaders';
+
+const blog = defineCollection({
+ loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
+ schema: z.object({
+ title: z.string(),
+ description: z.string(),
+ pubDate: z.coerce.date(),
+ updatedDate: z.coerce.date().optional(),
+ }),
+});
+```
+
+
+
+定义了集合类型（`type: 'content'` 或 `type: 'data'`）的集合 / （[`ContentCollectionInvalidTypeError`](/zh-cn/reference/errors/content-collection-invalid-type/)）
+不再有不同类型的集合。必须从集合定义中删除此项。
+
+```ts del={8}
+// src/content.config.ts
+import { defineCollection } from 'astro:content';
+import { z } from 'astro/zod';
+import { glob } from 'astro/loaders';
+
+const blog = defineCollection({
+ // 对于 content layer，你不再需要定义 `type`
+ type: 'content',
+ loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
+ schema: z.object({
+ title: z.string(),
+ description: z.string(),
+ pubDate: z.coerce.date(),
+ updatedDate: z.coerce.date().optional(),
+ }),
+});
+```
+
+
+
+旧版集合查询方法 `getDataEntryById()` 和 `getEntryBySlug()` / （[`GetEntryDeprecationError`](/zh-cn/reference/errors/get-entry-deprecation-error/)）
+将这两个方法都替换为 [`getEntry()`](/zh-cn/reference/modules/astro-content/#getentry)。
+
+
+
+
+依赖于 `slug` 属性的旧版集合查询和渲染方法 / （[`ContentSchemaContainsSlugError`](/zh-cn/reference/errors/content-schema-contains-slug-error/)）
+以前，`id` 基于文件名，还有一个可以在 URL 中使用的 `slug` 属性。现在 [CollectionEntry](/zh-cn/reference/modules/astro-content/#collectionentry) 的 `id` 就是 slug。如果你需要访问文件名（以前作为 `id` 可用），请使用 `filePath` 属性。将 `slug` 替换为 `id`：
+
+```astro ins={6} del={5} title="src/pages/[slug].astro"
+---
+export async function getStaticPaths() {
+ const posts = await getCollection('blog');
+ return posts.map((post) => ({
+ params: { slug: post.slug },
+ params: { slug: post.id },
+ props: post,
+ }));
+}
+---
+```
+
+
+
+使用 `entry.render()` 渲染的内容
+集合条目不再有 `render()` 方法。改为从 `astro:content` 导入 `render()` 函数并使用 `render(entry)`：
+
+```astro title="src/pages/index.astro" ins=", render" del={6} ins={7}
+---
+import { getEntry, render } from 'astro:content';
+
+const post = await getEntry('pages', 'homepage');
+
+const { Content, headings } = await post.render();
+const { Content, headings } = await render(post);
+---
+
+```
+
+
+
+ 请参阅 [Astro v5 升级指南](/zh-cn/guides/upgrade-to/v5/#旧版v20-内容集合-api) 了解之前 Astro v5 中旧版集合向后兼容性的指导以及将旧版集合升级到新 Content Layer API 的完整分步说明。
+
+### 已移除：`` 组件
+
+
+
+在 Astro 5.0 中，`` 组件被重命名为 `` 以阐明组件的角色。新名称更清楚地表明你从 Astro 的 `` 路由组件获得的功能与原生基于 CSS 的 MPA 路由略有不同。然而，已弃用版本的 `` 组件仍然存在，并且可能在 Astro 5.x 中工作。
+
+Astro 6.0 完全移除了 `` 组件，它不能再在你的项目中使用。更新到 `` 组件以继续使用这些功能。
+
+#### 我应该做什么？
+
+将所有 `ViewTransitions` 导入和组件的出现替换为 `ClientRouter`：
+
+```astro title="src/layouts/MyLayout.astro" del={1,7} ins={2,8}
+import { ViewTransitions } from 'astro:transitions';
+import { ClientRouter } from 'astro:transitions';
+
+
+
+ ...
+
+
+
+
+```
+
+了解更多关于 [Astro 中的视图过渡和客户端路由](/zh-cn/guides/view-transitions/)。
+
+### 已移除：`emitESMImage()`
+
+
+
+在 Astro 5.6.2 中，`emitESMImage()` 函数被弃用，推荐使用 `emitImageMetadata()`，后者移除了两个本意不是为公共使用而暴露的已弃用参数：`_watchMode` 和 `experimentalSvgEnabled`。
+
+Astro 6.0 完全移除 `emitESMImage()`。更新到 `emitImageMetadata()` 以保持当前行为。
+
+#### 我应该做什么？
+
+将所有 `emitESMImage()` 的出现替换为 `emitImageMetadata()` 并移除未使用的参数：
+
+```ts del={1,5} ins={2,6}
+import { emitESMImage } from 'astro/assets/utils';
+import { emitImageMetadata } from 'astro/assets/utils';
+
+const imageId = '/images/photo.jpg';
+const result = await emitESMImage(imageId, false, false);
+const result = await emitImageMetadata(imageId);
+```
+
+了解更多关于 [`emitImageMetadata()`](/zh-cn/reference/modules/astro-assets/#emitimagemetadata)。
+
+### 已移除：`Astro.glob()`
+
+
+
+在 Astro 5.0 中，`Astro.glob()` 被弃用，推荐使用 `getCollection()` 查询集合，以及 `import.meta.glob()` 查询项目中的其他源文件。
+
+Astro 6.0 完全移除 `Astro.glob()`。更新到 `import.meta.glob()` 以保持当前行为。
+
+#### 我应该做什么？
+
+将所有 `Astro.glob()` 的使用替换为 `import.meta.glob()`。请注意，`import.meta.glob()` 不再返回 `Promise`，因此你可能需要相应更新代码。你不需要对 [glob 模式](/zh-cn/guides/imports/#glob-模式) 进行任何更新。
+
+```astro title="src/pages/blog.astro" del={2} ins={3}
+---
+const posts = await Astro.glob('./posts/*.md');
+const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
+---
+
+{posts.map((post) => {post.frontmatter.title})}
+```
+
+在适当的情况下，考虑使用 [内容集合](/zh-cn/guides/content-collections/) 来组织你的内容，它有自己更新、更高性能的查询函数。
+
+你可能还想考虑使用 NPM 的 glob 包，如 [`fast-glob`](https://www.npmjs.com/package/fast-glob)。
+
+了解更多关于 [使用 `import.meta.glob` 导入文件](/zh-cn/guides/imports/#importmetaglob)。
+
+### 已移除：暴露的 `astro:actions` 内部实现
+
+
+
+在 Astro 5.x 中，一些内部实现从 `astro:actions` 导出，但这些本意不是为公共使用而暴露的。
+
+Astro 6.0 移除了以下函数、类和类型作为 `astro:actions` 虚拟模块的导出。这些不能再在你的项目文件中导入：
+
+- `ACTION_ERROR_CODES`
+- `ActionInputError`
+- `appendForwardSlash`
+- `astroCalledServerError`
+- `callSafely`
+- `deserializeActionResult`
+- `formDataToObject`
+- `getActionQueryString`
+- `serializeActionResult`
+- `type Actions`
+- `type ActionAccept`
+- `type AstroActionContext`
+- `type SerializedActionResult`
+
+#### 我应该做什么？
+
+将 `serializeActionResult()` 和 `deserializeActionResult()` 的所有导入替换为 `getActionContext()`。这两个方法现在可以通过 `getActionContext()` 使用：
+
+```ts title="src/middleware.ts" del={2} ins={3,6}
+import { defineMiddleware } from 'astro:middleware';
+import { serializeActionResult, deserializeActionResult } from 'astro:actions';
+import { getActionContext } from 'astro:actions';
+
+export const onRequest = defineMiddleware(async (context, next) => {
+ const { serializeActionResult, deserializeActionResult } = getActionContext(context);
+ // ...
+});
+```
+
+移除其他已移除导出的所有出现：
+
+```ts del={1-13}
+import {
+ ACTION_ERROR_CODES,
+ ActionInputError,
+ appendForwardSlash,
+ astroCalledServerError,
+ callSafely,
+ formDataToObject,
+ getActionQueryString,
+ type Actions,
+ type ActionAccept,
+ type AstroActionContext,
+ type SerializedActionResult,
+} from 'astro:actions';
+```
+
+了解更多关于 [Actions API 参考](/zh-cn/reference/modules/astro-actions/) 中所有可用的工具。
+
+### 已移除：路由中的百分号编码
+
+
+
+在 Astro 5.x 中，可以在文件名中包含百分号编码的百分号（`%25`）。
+
+Astro 6.0 出于安全原因移除了对文件名中 `%25` 字符的支持。此限制防止基于编码的安全绕过，其中 `%25` 解码为 `%`，可能导致歧义或无效的编码序列。
+
+#### 我应该做什么？
+
+如果你的路由文件名中有 `%25`，请重命名它们以使用不同的字符：
+
+```bash del={1} ins={2}
+src/pages/test%25file.astro
+src/pages/test-file.astro
+```
+
+### 已移除：`astro:ssr-manifest` 虚拟模块（集成 API）
+
+
+
+在 Astro 5.x 中，已弃用的 `astro:ssr-manifest` 虚拟模块仍然可用于访问配置值。
+
+Astro 6.0 完全移除了 `astro:ssr-manifest` 虚拟模块。集成或 Astro 内部不再使用它。manifest 现在通过集成钩子和适配器 API 直接传递，而不是通过虚拟模块。对于构建特定的 manifest 数据，使用 `astro:build:ssr` 集成钩子，它接收 manifest 作为参数。
+
+#### 我应该做什么？
+
+如果你的集成或代码从 `astro:ssr-manifest` 导入，改用 `astro:config/server` 访问配置值：
+
+```ts del={1} ins={2,3}
+import { manifest } from 'astro:ssr-manifest';
+import { srcDir, outDir, root } from 'astro:config/server';
+// 使用 srcDir、outDir、root 等获取配置值
+```
+
+了解更多关于 [`astro:config` 虚拟模块](/zh-cn/reference/modules/astro-config/)。
+
+### 已移除：`RouteData.generate()`（适配器 API）
+
+
+
+在 Astro 5.x 中，可以使用 `RouteData` 上的 `generate()` 方法生成路由。
+
+Astro 6.0 移除了 `RouteData.generate()`，因为路由生成现在由 Astro 内部处理。
+
+#### 我应该做什么？
+
+移除代码中对 `route.generate()` 的任何调用。此方法不再需要：
+
+```ts del={1}
+const generated = route.generate(params);
+```
+
+了解更多关于 [适配器 API](/zh-cn/reference/adapter-reference/)。
+
+### 已移除：`astro:build:done` 钩子上的 `routes`（集成 API）
+
+
+
+在 Astro 5.0 中，访问 `astro:build:done` 钩子上的 `routes` 被弃用。
+
+Astro 6.0 完全移除了传递给此钩子的 `routes` 数组。应该使用新的 `astro:routes:resolved` 钩子代替。
+
+#### 我应该做什么？
+
+移除传递给 `astro:build:done` 的任何 `routes` 实例，并用新的 `astro:routes:resolved` 钩子替换它。在新暴露的 `assets` map 上访问 `distURL`：
+
+```js title="my-integration.mjs" ins={2,6-8,11,13-18} del={10}
+const integration = () => {
+ let routes
+ return {
+ name: 'my-integration',
+ hooks: {
+ 'astro:routes:resolved': (params) => {
+ routes = params.routes
+ },
+ 'astro:build:done': ({
+ routes
+ assets
+ }) => {
+ for (const route of routes) {
+ const distURL = assets.get(route.pattern)
+ if (distURL) {
+ Object.assign(route, { distURL })
+ }
+ }
+ console.log(routes)
+ }
+ }
+ }
+}
+```
+
+了解更多用于构建集成的 [集成 API `astro:routes:resolved` 钩子](/zh-cn/reference/integrations-reference/#astroroutesresolved)。
+
+### 已移除：`astro:build:ssr` 钩子上的 `entryPoints`（集成 API）
+
+
+
+在 Astro 5.0 中，[`functionPerRoute` 被弃用](/zh-cn/guides/upgrade-to/v5/#弃用functionperroute适配器-api)。这意味着 `astro:build:ssr` 钩子上的 `entryPoints` 总是空的。
+
+Astro 6.0 完全移除了传递给此钩子的 `entryPoints` map。
+
+#### 我应该做什么？
+
+移除传递给 `astro:build:ssr` 的任何 `entryPoints` 实例：
+
+```js title="my-integration.mjs" del={6}
+const integration = () => {
+ return {
+ name: 'my-integration',
+ hooks: {
+ 'astro:build:ssr': (params) => {
+ someLogic(params.entryPoints)
+ },
+ }
+ }
+}
+```
+
+### 已移除：旧的 `app.render()` 签名（适配器 API）
+
+
+
+在 Astro 4.0 中，允许将 `routeData` 和 `locals` 作为可选参数传递的 `app.render()` 签名被弃用，推荐使用单个可选 `renderOptions` 参数。
+
+Astro 6.0 完全移除了此签名。尝试传递这些单独的参数现在将导致项目出错。
+
+#### 我应该做什么？
+
+检查你的 `app.render` 调用，将 `routeData` 和 `locals` 作为对象属性传递，而不是作为多个独立参数：
+
+```ts title="my-adapter/entrypoint.ts" del={1} ins={2}
+app.render(request, routeData, locals)
+app.render(request, { routeData, locals })
+```
+
+了解更多关于 [适配器 API](/zh-cn/reference/adapter-reference/)。
+
+### 已移除：`app.setManifestData()`（适配器 API）
+
+
+
+在 Astro 5.0 中，`app.setManifestData()` 方法在 `App` 和 `NodeApp` 上可用，但不再使用也不需要。
+
+Astro 6.0 完全移除了此方法。
+
+#### 我应该做什么？
+
+移除对 `app.setManifestData()` 的任何调用。如果需要更新 manifest，创建新的 `App` 实例。
+
+了解更多关于 [适配器 API](/zh-cn/reference/adapter-reference/)。
+
+### 已移除：`` 组件的 `handleForms` 属性
+
+
+
+在 Astro 4.0 中，`` 组件的 `handleForms` 属性被弃用，因为不再需要选择加入处理 `form` 元素的 `submit` 事件。此功能已内置为默认值，如果项目中仍然包含此属性，它静默无效。
+
+Astro 6.0 完全移除了此属性，现在必须移除它以避免项目出错。
+
+#### 我应该做什么？
+
+如果存在，从 `` 组件中移除 `handleForms` 属性。它没有提供额外功能，因此移除它不应改变项目中的任何行为：
+
+```astro title="src/pages/index.astro" del="handleForms"
+---
+import { ClientRouter } from "astro:transitions";
+---
+
+
+
+
+
+
+
+
+```
+
+了解更多关于 [表单的视图过渡动画](/zh-cn/guides/view-transitions/#transitions-with-forms)。
+
+### 已移除：`prefetch()` `with` 选项
+
+
+
+在 Astro 4.8.4 中，编程式 `prefetch()` 函数的 `with` 选项被弃用，推荐使用更合理的默认行为，不再需要为每个页面指定预取优先级。
+
+Astro 6.0 完全移除了此选项，不再可以通过传递 `with` 选项来配置预取优先级。尝试这样做现在将导致错误。
+
+默认情况下，Astro 的预取现在使用自动方法，将始终尝试使用 ``（如果支持），否则回退到 `fetch()`。
+
+#### 我应该做什么？
+
+检查你的 `prefetch()` 调用并移除 `with` 选项（如果仍然存在）：
+
+```ts del={1} ins={2}
+prefetch('/about', { with: 'fetch' });
+prefetch('/about');
+```
+
+了解更多关于 [预取](/zh-cn/guides/prefetch/)。
+
+### 已移除：Actions context 中的 `rewrite()`
+
+
+
+在 Astro 5.5.6 中，`ActionAPIContext.rewrite` 方法被弃用，因为应该使用自定义端点而不是重写。
+
+Astro 6.0 完全移除了 `ActionAPIContext` 中的 `rewrite()` 方法，不能再使用。
+
+#### 我应该做什么？
+
+检查你的 Actions 处理程序并移除对 `rewrite()` 的任何调用：
+
+
+```ts title="src/actions/index.ts" del={10}
+import { defineAction } from 'astro:actions';
+import { z } from 'astro/zod';
+
+export const server = {
+ getGreeting: defineAction({
+ input: z.object({
+ // ...
+ }),
+ handler: async (input, context) => {
+ context.rewrite('/')
+ // ...
+ }
+ })
+}
+```
+
+了解更多关于 [重写](/zh-cn/guides/routing/#重写)。
+
+### 已移除：schema 函数签名（内容加载器 API）
+
+
+
+在 Astro 5.x 中，内容加载器可以选择将 schema 定义为函数，而不是定义 Zod schema 对象进行验证。这对于根据配置选项或通过内省 API 动态生成 schema 很有用。
+
+Astro 6.0 移除了此签名，并为那些仍想在其内容加载器中动态定义 schema 的人引入了新的 `createSchema()` 属性作为替代。
+
+以旧方式提供 schema 函数将记录一条警告消息，说明加载器的 schema 被忽略，但否则加载器将继续工作，就像没有提供 schema 一样。在未来的主要版本中，提供 schema 函数的加载器将抛出错误并且无法使用。
+
+#### 我应该做什么？
+
+如果你正在构建内容加载器并使用函数动态返回集合 `schema` 属性，必须移除现有函数并使用新的 `createSchema()` 属性来定义 schema。
+
+例如，你可以直接使用 `zod-to-ts` 配合 `createSchema()` 和任何之前的函数逻辑来重现 Astro 之前的行为：
+
+```ts del={11} ins={2,12-22}
+import type { Loader } from 'astro/loaders'
+import { createTypeAlias, zodToTs } from 'zod-to-ts'
+import { getSchemaFromApi } from './utils'
+
+function myLoader() {
+ return {
+ name: 'my-loader',
+ load: async (context) => {
+ // ...
+ },
+ schema: async () => await getSchemaFromApi(),
+ createSchema: async () => {
+ const schema = await getSchemaFromApi()
+ const identifier = 'Entry'
+ const { node } = zodToTs(schema, identifier)
+ const typeAlias = createTypeAlias(node, identifier)
+
+ return {
+ schema,
+ types: `export ${typeAlias}`
+ }
+ }
+ } satisfies Loader
+}
+```
+
+了解更多关于内容加载器 API 参考中的 [`createSchema()`](/en/reference/content-loader-reference/#loadercreateschema)。
+
+### 已移除：session `test` driver
+
+
+
+在 Astro 5.x 中，内部 session `test` driver 在 Astro 配置类型中导出，但它本意不是为公共使用而暴露的。
+
+Astro 6.0 移除了 session `test` driver，因为它不再在内部用于测试 `context.session`。
+
+#### 我应该做什么？
+
+你不太可能正在使用这个内部 API。如果你正在使用，必须移除对 session `test` driver 的任何使用：
+
+```js title="astro.config.mjs" del={2,6-9}
+import { defineConfig } from 'astro/config'
+import { createMockStorage } from './utils'
+
+export default defineConfig({
+ session: {
+ driver: 'test',
+ options: {
+ mockStorage: createMockStorage()
+ }
+ }
+})
+```
+
+了解更多关于 [Session Driver API](/zh-cn/reference/session-driver-reference/)。
+
+### 已移除：对 CommonJS 配置文件的支持
+
+
+
+在 Astro 5.x 中，Astro 配置文件可以使用以下任何扩展名：`.mjs`、`.js`、`.ts`、`.mts`、`.cjs` 和 `.cts`。
+
+Astro 6.0 移除了 `.cjs` 和 `.cts` 扩展名。
+
+#### 我应该做什么？
+
+如果你有 `astro.config.cjs` 或 `astro.config.cts` 文件，更新它以使用支持的扩展名：`.mjs`、`.js`、`.ts` 或 `.mts`。
+
+了解更多关于 [Astro 配置文件](/zh-cn/guides/configuring-astro/#astro-配置文件)。
+
+### 实验性标志
+
+实验性标志允许你在功能处于早期开发阶段时选择加入。Astro 也可能使用实验性标志来测试对默认行为的破坏性变更。以下实验性标志已在 Astro 6.0 中移除，现在已稳定或成为新的默认行为。
+
+如果你之前使用过这些实验性标志，请从 Astro 配置中移除它们：
+
+```js del={5-11} title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+ experimental: {
+ csp: true,
+ fonts: true,
+ liveContentCollections: true,
+ preserveScriptOrder: true,
+ staticImportMetaEnv: true,
+ headingIdCompat: true,
+ failOnPrerenderConflict: true
+ },
+})
+```
+
+#### 现在稳定的功能：
+
+- `csp`（请参阅 [`security.csp` 配置参考](/en/reference/configuration-reference/#securitycsp) 了解更多关于内容安全策略的信息。）
+- `fonts`（请参阅更新的 [字体指南](/zh-cn/guides/fonts/) 了解更多关于向项目添加自定义字体的信息。）
+- `liveContentCollections`（请参阅更新的 [内容集合文档](/zh-cn/guides/content-collections/) 了解更多关于实时集合的信息。）
+- `failOnPrerenderConflict`（请参阅新的 [`prerenderConflictBehavior`](/en/reference/configuration-reference/#prerenderconflictbehavior) 配置选项。）
+
+#### 新的默认或推荐行为：
+
+- `preserveScriptOrder`（请参阅下面关于 [默认 `
+
+```
+
+了解更多关于 [使用 `script`](/zh-cn/guides/client-side-scripts/) 和 [`style`](/zh-cn/guides/styling/) 标签。
+
+### 变更：响应式图片样式的生成方式
+
+
+
+在 Astro 5.x 中，图片在运行时计算，`fit` 和 `pos` 响应式图片样式在 `style` 属性中注入。这在许多情况下无法与 Astro 的内容安全策略（CSP）兼容。
+
+Astro 6 在构建时根据项目配置在虚拟模块中生成图片样式，产生一个哈希类和 `data-*` 属性来为图片应用响应式样式。
+
+#### 我应该做什么？
+
+直观检查你的图片以确保它们按预期渲染。这是一个实现细节，不应影响响应式图片的预期使用。
+
+但是，如果你之前依赖为图片生成的内联样式：
+
+```html
+![]()
+```
+
+那么你需要更新项目代码以使用新的 `data-*` 属性：
+
+```html
+![]()
+```
+
+## 破坏性变更
+
+以下更改被认为是 Astro v6.0 中的破坏性变更。破坏性变更可能会或可能不会提供临时向后兼容性。如果你正在使用这些功能，可能需要按照每个条目中的建议更新代码。
+
+### 变更：带文件扩展名的端点不能使用尾随斜杠访问
+
+
+
+在 Astro v5.0 中，URL 以文件扩展名结尾的自定义端点（例如 `/src/pages/sitemap.xml.ts`）可以使用尾随斜杠（`/sitemap.xml/`）或不使用尾随斜杠（`/sitemap.xml`）访问，无论 `build.trailingSlash` 配置为何值。
+
+在 Astro v6.0 中，这些端点只能不带尾随斜杠访问。无论你的 `build.trailingSlash` 配置如何，这都是正确的。
+
+#### 我应该做什么？
+
+检查你的自定义端点链接（URL 中包含文件扩展名），并移除任何尾随斜杠：
+
+```html del={1} ins={2} title="src/pages/index.astro"
+Sitemap
+Sitemap
+```
+
+了解更多关于 [自定义端点](/zh-cn/guides/endpoints/)。
+
+### 变更：`import.meta.env` 值始终内联
+
+
+
+在 Astro 5.13 中，引入了 `experimental.staticImportMetaEnv` 标志，用于更新直接访问 `import.meta.env` 时的行为，以与 [Vite 的环境变量处理方式](https://vite.dev/guide/env-and-mode.html#env-variables) 保持一致，并确保 `import.meta.env` 值始终内联。
+
+在 Astro 5.x 中，非公共环境变量被替换为对 `process.env` 的引用。此外，Astro 还可能转换通过 `import.meta.env` 使用的环境变量的值类型，这可能阻止访问某些值，如字符串 `"true"`（被转换为布尔值）和 `"1"`（被转换为数字）。
+
+Astro 6 移除了这个实验性标志，并将其作为 Astro 的新默认行为：`import.meta.env` 值始终内联且不会被强制转换。
+
+#### 我应该做什么？
+
+如果你之前使用过这个实验性功能，必须 [从配置中移除此实验性标志](#实验性标志)，因为它不再存在。
+
+如果你依赖强制转换，可能需要更新项目代码以手动应用它：
+
+```ts title="src/components/MyComponent.astro" del={1} ins={2}
+const enabled: boolean = import.meta.env.ENABLED;
+const enabled: boolean = import.meta.env.ENABLED === "true";
+```
+
+如果你依赖转换为 `process.env`，可能需要更新项目代码以手动应用它：
+
+```ts title="src/components/MyComponent.astro" del={1} ins={2}
+const enabled: boolean = import.meta.env.DB_PASSWORD;
+const enabled: boolean = process.env.DB_PASSWORD;
+```
+
+你可能还需要更新类型：
+
+```ts title="src/env.d.ts" del={3-4} ins={5,12-16}
+interface ImportMetaEnv {
+ readonly PUBLIC_POKEAPI: string;
+ readonly DB_PASSWORD: string;
+ readonly ENABLED: boolean;
+ readonly ENABLED: string;
+}
+
+interface ImportMeta {
+ readonly env: ImportMetaEnv;
+}
+
+namespace NodeJS {
+ interface ProcessEnv {
+ DB_PASSWORD: string;
+ }
+}
+```
+
+如果你需要更多对 Astro 中环境变量的控制，我们建议使用 `astro:env`。
+
+了解更多关于 Astro 中的 [环境变量](/zh-cn/guides/environment-variables/)，包括 `astro:env`。
+
+### 变更：默认图片服务中默认裁剪
+
+
+
+在 Astro 5.0 中，默认图片服务仅在提供 `fit` 选项时才应用裁剪。
+
+Astro 6.0 默认应用裁剪，无需设置 `fit` 选项。
+
+#### 我应该做什么？
+
+你现有的裁剪图片不需要任何更改，因为 `fit` 属性仍然有效。但是，如果你之前设置 `fit` 为 `contain`（其默认值）来裁剪图片，你现在可以移除此选项，仅通过指定 `width` 和 `height` 就能达到相同的裁剪行为：
+
+```ts title="src/components/MyImage.astro" del={5} ins={6}
+---
+import { Image } from 'astro:assets';
+import myImage from '../assets/photo.jpg';
+---
+
+
+```
+
+### 变更：默认图片服务中永不放大图片
+
+
+
+在 Astro 5.x 中，当请求的尺寸大于源图片时，默认图片服务会放大图片。
+
+Astro 6.0 移除了此行为：默认图片服务永不放大图片。
+
+#### 我应该做什么？
+
+检查你的图片并根据需要更新尺寸。如果你确实需要放大图片，可以考虑手动放大图片或使用支持放大的自定义图片服务。
+
+### 变更：SVG 栅格化
+
+
+
+在 Astro v5.x 中，Astro 的默认 Sharp 图片服务无法将 SVG 文件转换为栅格文件（例如 PNG、WebP）。这意味着 `` 组件在优化和转换 SVG 文件时会忽略为 `format` 设置的任何值。
+
+Astro 6.0 现在支持 SVG 栅格化。这受 [许多限制](https://github.com/lovell/sharp/issues?q=is%3Aissue%20state%3Aopen%20svg) 影响，例如，带有嵌入字体的 SVG 可能无法正确转换。但是，当设置 `format` 属性时，图片服务现在会尝试转换 SVG 图片。
+
+#### 我应该做什么？
+
+如果你之前依赖图片服务会自动跳过转换 SVG 这一事实，你现在必须预先检查图片格式以避免将 SVG 转换为栅格图片：
+
+```astro del={1} ins={3-7}
+
+
+
+```
+
+了解更多关于 [`format` 图片属性](/zh-cn/reference/modules/astro-assets/#format)
+
+### 变更：在客户端调用 `getImage()` 时抛出错误
+
+
+
+在 Astro 5.x 中，在客户端从 `astro:assets` 调用 `getImage()` 会静默失败或产生不正确的结果。
+
+Astro 6.0 在客户端调用 `getImage()` 时抛出运行时错误。
+
+#### 我应该做什么？
+
+在服务器上调用 `getImage()` 并将结果的 `src` 传递给客户端：
+
+```astro title="src/components/ClientImage.astro" {5, 8, 11}
+---
+import { getImage } from "astro:assets";
+import myBackground from "../background.png";
+
+const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
+---
+
+
+
+
+```
+
+请参阅 [使用 `getImage()` 生成图片](/zh-cn/guides/images/#使用-getimage-生成图像) 获取完整示例。
+
+### 变更：Markdown 标题 ID 生成
+
+
+
+在 Astro 5.x 中，对 Markdown 的额外默认处理步骤会从以特殊字符结尾的章节标题的 ID 末尾剥离尾随连字符。这提供了更干净的 `id` 值，但可能导致你的 Markdown 在不同平台间渲染不兼容。
+
+在 Astro 5.5 中，引入了 `experimental.headingIdCompat` 标志，允许你使用流行的 [`github-slugger`](https://github.com/Flet/github-slugger) 包使 Astro 为 Markdown 标题生成的 ID 与 GitHub 和 npm 等常见平台兼容。
+
+Astro 6.0 移除了这个实验性标志，并将其作为 Astro 的新默认行为：以特殊字符结尾的标题 ID 末尾的尾随连字符不再被移除。
+
+#### 我应该做什么？
+
+如果你有手动链接到标题的链接，可能需要用新的尾随连字符更新锚链接值。例如，以下 Markdown 标题：
+
+```md
+## ``
+```
+
+现在会生成以下 HTML，标题 `id` 中有尾随连字符：
+
+```html ins="-"
+<Picture />
+```
+
+现在必须这样链接：
+
+```markdown ins="-"
+See [the Picture component](/en/guides/images/#picture-) for more details.
+```
+
+如果你之前使用实验性功能来强制尾随连字符，必须 [从配置中移除此实验性标志](#实验性标志)，因为它不再存在。
+
+如果你之前直接使用 `rehypeHeadingIds` 插件来强制兼容性，移除 `headingIdCompat` 选项，因为它不再存在：
+
+```js title="astro.config.mjs" del={8} ins={9}
+import { defineConfig } from 'astro/config';
+import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';
+
+export default defineConfig({
+ markdown: {
+ rehypePlugins: [
+ [rehypeHeadingIds, { headingIdCompat: true }],
+ [rehypeHeadingIds],
+ otherPluginThatReliesOnHeadingIDs,
+ ],
+ },
+});
+```
+
+如果你想保持旧的 ID 生成以实现向后兼容，可以创建一个自定义 rehype 插件，它将像 Astro 5.x 一样生成标题 ID。这将允许你继续使用现有的锚链接而无需添加尾随连字符。
+
+
+
+创建自定义 rehype 插件来剥离尾随连字符
+
+
+
+1. 安装所需依赖：
+
+
+
+ ```sh
+ npm i github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string
+ ```
+
+
+ ```sh
+ pnpm add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string
+ ```
+
+
+ ```sh
+ yarn add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string
+ ```
+
+
+
+2. 创建一个自定义 rehype 插件，它将像 Astro v5 一样生成标题 ID：
+
+ ```js title="plugins/rehype-slug.mjs"
+ import GithubSlugger from 'github-slugger';
+ import { headingRank } from 'hast-util-heading-rank';
+ import { visit } from 'unist-util-visit';
+ import { toString } from 'hast-util-to-string';
+
+ const slugs = new GithubSlugger();
+
+ export function rehypeSlug() {
+ /**
+ * @param {import('hast').Root} tree
+ */
+ return (tree) => {
+ slugs.reset();
+ visit(tree, 'element', (node) => {
+ if (headingRank(node) && !node.properties.id) {
+ let slug = slugs.slug(toString(node));
+ // 像 Astro v5 及以下版本一样剥离尾随连字符：
+ if (slug.endsWith('-')) slug = slug.slice(0, -1);
+ node.properties.id = slug;
+ }
+ });
+ };
+ }
+ ```
+
+3. 将自定义插件添加到 `astro.config.mjs` 中的 Markdown 配置：
+
+ ```js title="astro.config.mjs" ins={2} ins="rehypeSlug"
+ import { defineConfig } from 'astro/config';
+ import { rehypeSlug } from './plugins/rehype-slug';
+
+ export default defineConfig({
+ markdown: {
+ rehypePlugins: [rehypeSlug],
+ },
+ });
+ ```
+
+
+
+
+
+了解更多关于 [标题 ID](/zh-cn/guides/markdown-content/#标题-id)。
+
+### 变更：`getStaticPaths()` 不能返回数字类型的 `params`
+
+
+
+在 Astro 5.x 中，`getStaticPaths()` 可以返回数字类型的 `params`，Astro 会始终将其字符串化。然而，这可能导致混淆，因为它与 `Astro.params` 类型冲突。
+
+Astro 6.0 移除了此行为：`getStaticPaths()` 现在必须返回字符串或 undefined 类型的 `params` 值。
+
+#### 我应该做什么？
+
+检查使用 `getStaticPaths()` 的动态路由，并将任何数字参数转换为字符串：
+
+```astro title="src/pages/post/[id]/[label].astro" del={6,13} ins={7,14}
+---
+export function getStaticPaths() {
+ return [
+ {
+ params: {
+ id: 1,
+ id: "1",
+ label: "foo",
+ }
+ },
+ {
+ params: {
+ id: 2,
+ id: "2",
+ label: "bar",
+ }
+ },
+ ]
+}
+---
+```
+
+了解更多关于 [使用 `getStaticPaths()` 动态 SSG 路由](/zh-cn/guides/routing/#静态-ssg-模式)。
+
+### 变更：Astro 组件不能在 Vitest 客户端环境中渲染（容器 API）
+
+
+
+在 Astro 5.x 中，禁止在客户端渲染 Astro 组件。然而，我们在 Vitest 客户端环境（如 `jsdom` 或 `happy-dom`）中使用 [实验性容器 API](/zh-cn/reference/container-reference/) 临时允许了这种行为。
+
+Astro 6.0 移除了在 Vitest 客户端环境中渲染 Astro 组件的能力：渲染 Astro 组件的测试现在必须在 `node` 等服务器环境中运行。
+
+#### 我应该做什么？
+
+如果你使用 Vitest 在 `jsdom` 或 `happy-dom` 等客户端环境中运行渲染 Astro 组件的测试，请更新 Vitest 配置以使用 `node` 环境：
+```ts title="vitest.config.ts" del={5} ins={6}
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ environment: 'jsdom',
+ environment: 'node',
+ },
+});
+```
+
+了解更多关于 [测试 Astro 组件](/zh-cn/guides/testing/)。
+
+### 变更：Rollup 输出文件名配置路径（Vite 配置）
+
+
+
+在 Astro 5.x 中，客户端资源的自定义 Rollup 输出文件名选项可以在 `vite.build.rollupOptions.output` 配置。
+
+Astro 6.0 将客户端构建输出配置范围限定到 Vite 的客户端环境。如果你为客户端资源自定义 `entryFileNames`、`chunkFileNames` 或 `assetFileNames`，请使用 `vite.environments.client.build.rollupOptions.output`。
+
+#### 我应该做什么？
+
+将配置从 `vite.build.rollupOptions.output` 移动到 `vite.environments.client.build.rollupOptions.output`：
+
+```js title="astro.config.mjs"
+export default defineConfig({
+ vite: {
+ environments: {
+ client: {
+ build: {
+ rollupOptions: {
+ output: {
+ entryFileNames: 'js/[name]-[hash].js',
+ },
+ },
+ },
+ },
+ },
+ },
+});
+```
+
+### 变更：集成钩子和 HMR 访问模式（集成 API）
+
+
+
+在 Astro 5.x 中，Astro 依赖某些集成钩子和 HMR 访问模式，这些模式与 Vite 的 Environment API 不兼容或可以通过集成它来改进。
+
+Astro 6.0 使用 Vite 新的 Environment API 进行构建配置和开发服务器交互。这主要启用了 workerd 等运行时中的开发模式，但意味着一些集成钩子和 HMR 访问模式已更改。
+
+#### 我应该做什么？
+
+**对于使用 `astro:build:setup` 的集成：**
+
+钩子现在只调用一次，配置所有环境（`ssr`、`client`、`prerender`），而不是为每个构建目标单独调用。移除 `target` 参数并使用 `vite.environments` 配置特定环境：
+
+```ts title="my-integration.mjs" del={3-7} ins={8-10}
+{
+ hooks: {
+ 'astro:build:setup': ({ target, vite }) => {
+ if (target === 'client') {
+ vite.build.minify = false;
+ }
+ }
+ 'astro:build:setup': ({ vite }) => {
+ vite.environments.client.build.minify = false;
+ }
+ }
+}
+```
+
+**对于访问 HMR 的开发工具栏和集成代码：**
+
+将 `server.hot.send()` 替换为 `server.environments.client.hot.send()`：
+
+```ts del={1} ins={2}
+server.hot.send(event)
+server.environments.client.hot.send(event)
+```
+
+了解更多关于 [Vite Environment API](https://vite.dev/guide/api-environment) 和 Astro [集成钩子](/zh-cn/reference/integrations-reference/#astrobuildsetup)。
+
+### 变更：`SSRManifest` 接口结构（适配器 API）
+
+
+
+在 Astro 5.x 中，`SSRManifest` 接口的路径属性（如 `srcDir`、`outDir`、`cacheDir`、`publicDir`、`buildClientDir` 和 `buildServerDir`）是 URL 字符串。
+
+Astro 6.0 将这些路径属性的形式从 URL 字符串更改为 `URL` 对象。通过此更改，manifest 上现在有几个新属性可用，其他属性已更新或移除。
+
+#### 我应该做什么？
+
+如果你之前将这些路径属性视为字符串，现在需要处理 `URL` 对象。例如，现在需要访问 `URL` 对象的 `href` 属性：
+
+```ts del={2} ins={3}
+// 要获取相同的格式（例如 "file:///path/to/src"），进行以下更改：
+const srcPath = manifest.srcDir;
+const srcPath = manifest.srcDir.href;
+```
+
+如果你之前访问 `hrefRoot` 属性，需要移除它，因为它在 manifest 上不再可用。
+
+更新对 `serverIslandMappings` 和 `sessionDriver` 的任何使用。它们现在是异步方法：
+
+```ts del={1,2} ins={3,4}
+const mappings = manifest.serverIslandMappings;
+const driver = manifest.sessionDriver;
+const mappings = await manifest.serverIslandMappings?.();
+const driver = await manifest.sessionDriver?.();
+```
+
+了解更多关于 [适配器 API](/zh-cn/reference/adapter-reference/)。
+
+### 变更：schema 类型被推断而不是生成（内容加载器 API）
+
+
+
+在 Astro 5.x 中，当内容加载器提供且用户未定义 schema 时，内容集合的类型是使用 `zod-to-ts` 生成的。
+
+Astro 6.0 移除了此行为：类型不再使用 `zod-to-ts` 生成。相反，类型被推断。
+
+#### 我应该做什么？
+
+如果你在内容加载器中提供 `schema`，必须使用 [TypeScript 的 `satisfies` 运算符](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator)：
+
+```ts del={3,11} ins={4,12}
+import type { Loader } from 'astro/loaders'
+
+function myLoader(): Loader {
+function myLoader() {
+ return {
+ name: 'my-loader',
+ load: async (context) => {
+ // ...
+ },
+ schema: z.object({/* ... */})
+ }
+ } satisfies Loader
+}
+```
+
+了解更多关于 [定义加载器 schema 类型](/zh-cn/reference/content-loader-reference/#loader-对象)。
+
+## 已知问题
+
+请查看 [Astro 在 GitHub 上的 issues](https://github.com/withastro/astro/issues/) 了解任何已报告的问题，或自行提交 issue。