升级到 Astro v3

本指南将帮助您从 Astro v2 迁移到 Astro v3。

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

升级 Astro

使用您的包管理器将 Astro 项目的版本更新到最新。如果您正在使用 Astro 集成，请也将其更新到最新版本。

# Upgrade to Astro v3.x
npm install astro@latest

# Example: upgrade React and Tailwind integrations
npm install @astrojs/react@latest @astrojs/tailwind@latest

# Upgrade to Astro v3.x
pnpm add astro@latest

# Example: upgrade React and Tailwind integrations
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

# Upgrade to Astro v3.x
yarn add astro@latest

# Example: upgrade React and Tailwind integrations
yarn add @astrojs/react@latest @astrojs/tailwind@latest

Astro v3.0 实验性标志已移除

从 astro.config.mjs 中移除以下实验性标志

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true,
    viewTransitions: true,
  },
})

这些功能现在默认可用

用于动画页面过渡和持久化岛屿的视图过渡。如果您使用了此实验性标志，请参阅视图过渡 API 破坏性变更和升级建议。
一个新图像服务 API astro:assets，用于在 Astro 中使用图像，包括新的 <Image /> 组件和 getImage() 函数。请阅读详细的图像升级建议，无论您是否使用此实验性标志，以了解这可能如何影响您的项目。

在3.0 博客文章中阅读更多关于这两个激动人心的功能！

Astro v3.0 破坏性变更

Astro v3.0 包含一些破坏性变更，并移除了之前一些已弃用的功能。如果您的项目在升级到 v3.0 后未按预期工作，请查阅本指南以获取所有破坏性变更的概述以及如何更新代码库的说明。

请参阅更新日志以获取完整的发布说明。

已移除：对 Node 16 的支持

Node 16 计划于 2023 年 9 月达到其生命周期结束。

Astro v3.0 完全取消了对 Node 16 的支持，以便所有 Astro 用户都可以利用 Node 更现代的特性。

我应该怎么做？

请检查您的开发环境和部署环境是否都使用 Node 18.14.1 或更高版本。

使用以下命令检查您本地的 Node 版本
终端窗口
```
node -v
```
查阅您的部署环境自己的文档，以验证它们是否支持 Node 18。

您可以在仪表板配置设置中或 .nvmrc 文件中为您的 Astro 项目指定 Node 18.14.1。
.nvmrc
```
18.14.1
```

已移除：对 TypeScript 4 的支持

在 Astro v2.x 中，tsconfig.json 预设包括对 TypeScript 4.x 和 5.x 的支持。

Astro v3.0 将 tsconfig.json 预设更新为仅支持 TypeScript 5.x。Astro 现在假定您使用 TypeScript 5.0（2023 年 3 月），或者您的编辑器包含它（例如 VS Code 1.77）。

我应该怎么做？

如果您在本地安装了 TypeScript，请更新到至少 v5.0。

npm install typescript@latest --save-dev

已移除：`@astrojs/image`

在 Astro v2.x 中，Astro 提供了一个官方图像集成，其中包括 Astro <Image /> 和 <Picture /> 组件。

Astro v3.0 完全从代码库中移除了此集成。Astro 新的图像解决方案是一个内置的图像服务 API：astro:assets。

我应该怎么做？

从您的项目中移除 @astrojs/image 集成。您不仅需要卸载该集成，还需要更新或移除所有导入语句以及现有的 <Image /> 和 <Picture /> 组件。您可能还需要配置一个首选的默认图像处理服务。

您将在我们的图像指南中找到移除旧图像集成的完整分步说明。

迁移到 astro:assets 也将带来一些您现在可能希望使用的新图像选项和功能。请参阅完整的v3.0 图像升级建议以获取完整详细信息！

import { defineConfig } from 'astro/config';
import image from '@astrojs/image';

export default defineConfig({
  integrations: [
    image(),
  ]
})

已移除：`<Markdown />` 组件

在 Astro v1.x 中，Astro 弃用了 <Markdown /> 组件并将其移至外部包。

Astro v3.0 完全移除了 @astrojs/markdown-component 包。Astro 的 <Markdown /> 组件将不再在您的项目中工作。

我应该怎么做？

移除所有 @astrojs/markdown-component 的实例。

---
import Markdown from '@astrojs/markdown-component';
---

要在代码中继续使用类似的 <Markdown /> 组件，请考虑使用社区集成，例如 astro-remote。请务必根据该集成自己的文档，更新您的 <Markdown /> 组件导入和属性。

否则，请删除您的 .astro 文件中所有导入 Astro 的 <Markdown /> 组件以及组件本身的引用。您需要直接将内容重写为 HTML，或从 .md 文件导入 Markdown。

已移除：已弃用的 1.x API

在 Astro v1.x 中，Astro 弃用了我们最初的配置设置以及 <style global> 和 <script hoist> 支持。然而，这些仍然为了向后兼容而受到支持。

Astro v3.0 完全移除了这些已弃用的 API。应改用官方支持的配置设置以及现代的 <style is:global> 和 <script> 语法。

我应该怎么做？

如果您继续使用 v1.x API，请改用每个功能的新 API

已弃用的配置选项：请参阅0.26 迁移指南
已弃用的脚本/样式属性类型：请参阅0.26 迁移指南

已移除：服务器代码中 Web API 的部分垫片

在 Astro v2.x 中，Astro 在服务器渲染的代码中为 document 或 localStorage 等 Web API 提供了部分垫片。这些垫片通常不完整且不可靠。

Astro v3.0 完全移除了这些部分垫片。Web API 不再在服务器渲染的代码中可用。

我应该怎么做？

如果您在服务器渲染的组件中使用 Web API，您需要有条件地使用这些 API 或使用 client:only 客户端指令。

已移除：内容集合 schema 中 `astro:content` 的 `image`

在 Astro v2.x 中，内容集合 API 弃用了从 astro:content 导出的 image，用于您的内容集合 schema 中。

Astro v3.0 完全移除了此导出。

我应该怎么做？

如果您正在使用已弃用的 astro:content 中的 image()，请将其移除，因为它已不再存在。请改为通过 schema 中的 image 辅助函数验证图像。

import { defineCollection, z, image } from "astro:content";
import { defineCollection, z } from "astro:content";

defineCollection({
  schema: ({ image }) =>
    z.object({
      image: image(),
   }),
});

已移除：0.14 版之前的 Shiki 主题名称

在 Astro v2.x 中，一些 Shiki 主题名称已被重命名，但为了向后兼容保留了原始名称。

Astro v3.0 移除了原始名称，转而使用重命名后的主题名称。

我应该怎么做？

如果您的项目使用了以下任何主题，请将其重命名为更新后的名称

material-darker -> material-theme-darker
material-default -> material-theme
material-lighter -> material-theme-lighter
material-ocean -> material-theme-ocean
material-palenight -> material-theme-palenight

已移除：`class:list` 特性

在 Astro v2.x 中，class:list 指令使用了一个受 clsx 启发并带有一些额外功能（如去重和 Set 支持）的自定义实现。

Astro v3.0 现在直接为 class:list 使用 clsx，它不支持去重或 Set 值。

我应该怎么做？

将传递给 class:list 指令的任何 Set 元素替换为普通的 Array。

<Component class:list={[
  'a',
  'b',
  new Set(['c', 'd'])
  ['c', 'd']
]} />

已移除：将 `class:list` 作为 prop 传递

在 Astro v2.x 中，class:list 值通过 Astro.props['class:list'] 传递给组件。

Astro v3.0 在将 class:list 值通过 Astro.props['class'] 传递给组件之前，会将其规范化为字符串。

我应该怎么做？

移除任何期望接收 class:list prop 的代码。

---
import { clsx } from 'clsx';
const { class: className, 'class:list': classList } = Astro.props;
const { class: className } = Astro.props;
---
<div
  class:list={[className, classList]}
  class:list={[className]}
/>

已移除：camelCase CSS 变量的 kebab-case 转换

在 Astro v2.x 中，传递给 style 属性的 camelCase CSS 变量会同时渲染为 camelCase（按原样编写）和 kebab-case（为向后兼容保留）。

Astro v3.0 移除了这些 camelCase CSS 变量名称的 kebab-case 转换，只渲染原始的 camelCase CSS 变量。

---
const myValue = "red"
---
<!-- input -->
<div style={{ "--myValue": myValue }}></div>

<!-- output (Astro 2.x) -->
<div style="--my-value:var(--myValue);--myValue:red"></div>
<!-- output (Astro 3.0) -->
<div style="--myValue:red"></div>

我应该怎么做？

如果您之前依赖 Astro 在样式中进行 kebab-case 转换，请将您现有的样式更新为 camelCase，以防止样式丢失。例如

<style>
  div {
   color: var(--my-value);
   color: var(--myValue);
  }
</style>

已移除：`getStaticPaths()` 返回值的自动扁平化

在 Astro v2.x 中，getStaticPaths() 的返回值会自动扁平化，允许您返回一个数组的数组而不会出错。

Astro v3.0 移除了 getStaticPaths() 结果的自动扁平化。

我应该怎么做？

如果您返回的是一个数组的数组，而不是一个对象数组（这是预期），则现在应该使用 .flatMap 和 .flat 来确保您返回的是一个扁平数组。

如果需要更新代码，将提供一条错误消息，指出 getStaticPath() 的返回值必须是一个对象数组。

已迁移：`astro check` 现在需要一个外部包

在 Astro v2.x 中，astro check 默认包含在 Astro 中，并且其依赖项也捆绑在 Astro 中。这意味着无论您是否使用 astro check，包都会更大。这也阻止了您控制要使用的 TypeScript 和 Astro 语言服务器版本。

Astro v3.0 将 astro check 命令从 Astro 核心中移出，现在需要一个外部包 @astrojs/check。此外，您必须在项目中安装 typescript 才能使用 astro check 命令。

我应该怎么做？

升级到 Astro v3.0 后运行 astro check 命令，并按照提示安装所需的依赖项，或者手动将 @astrojs/check 和 typescript 安装到您的项目中。

已弃用：`build.excludeMiddleware` 和 `build.split`

在 Astro v2.x 中，build.excludeMiddleware 和 build.split 用于在使用适配器以 SSR 模式运行时更改特定文件的发出方式。

Astro v3.0 用新的SSR 适配器配置选项替换了这些构建配置选项，以执行相同的任务：edgeMiddleware 和 functionPerRoute。

我应该怎么做？

现在直接在适配器配置中使用新选项更新 Astro 配置文件。

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/serverless";

export default defineConfig({
    build: {
      excludeMiddleware: true
    },
    adapter: vercel({
      edgeMiddleware: true
    }),
});

import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify/functions";

export default defineConfig({
     build: {
        split: true
     },
     adapter: netlify({
        functionPerRoute: true
     }),
});

已弃用：`markdown.drafts`

在 Astro v2.x 中，markdown.drafts 配置允许您在运行开发服务器时使用草稿页面，但不在生产环境中构建。

Astro v3.0 弃用了此功能，转而支持内容集合通过手动过滤来处理草稿页面的方法，这提供了对该功能的更多控制。

我应该怎么做？

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

已弃用：在端点中返回简单对象

在 Astro v2.x 中，端点可以返回一个简单对象，该对象将被转换为 JSON 响应。

Astro v3.0 弃用了此行为，转而支持直接返回 Response 对象。

我应该怎么做？

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

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

如果您确实需要保留以前的格式，可以使用 ResponseWithEncoding 对象，但该对象将来会被弃用。

export async function GET() {
  return { body: { "title": "Bob's blog" } };
  return new ResponseWithEncoding({ body: { "title": "Bob's blog" }});
}

默认值已更改：tsconfig.json 预设中的 `verbatimModuleSyntax`

在 Astro v2.x 中，verbatimModuleSyntax 设置默认关闭，其 TypeScript 4.x 等效项 importsNotUsedAsValues 在 strict 预设中启用。

在 Astro v3.0 中，verbatimModuleSyntax 在所有预设中默认启用。

我应该怎么做？

此选项要求使用 import type 语法导入类型。

---
import { type CollectionEntry, getEntry } from "astro:content";
---

虽然我们建议保持启用并使用 type 正确进行类型导入（如上所示），但如果它导致任何问题，您可以通过在 tsconfig.json 文件中设置 verbatimModuleSyntax: false 来禁用它。

{
  "compilerOptions": {
    "verbatimModuleSyntax": false
  }
}

默认值已更改：端口 `3000`

在 Astro v2.x 中，Astro 默认运行在端口 3000 上。

Astro v3.0 将默认端口更改为 4321。🚀

我应该怎么做？

更新任何对 localhost:3000 的现有引用，例如在测试或您的 README 中，以反映新端口 localhost:4321。

默认值已更改：import.meta.env.BASE_URL `trailingSlash`

在 Astro v2.x 中，import.meta.env.BASE_URL 默认会在您的 base 设置后附加一个尾部斜杠。trailingSlash: "ignore" 也会附加一个尾部斜杠。

Astro v3.0 不再默认在 import.meta.env.BASE_URL 后附加尾部斜杠，当设置 trailingSlash: "ignore" 时也不再附加。（base 与 trailingSlash: "always" 或 trailingSlash: "never" 组合的现有行为保持不变。）

我应该怎么做？

如果您的 base 已经有尾部斜杠，则无需更改。

如果您的 base 没有尾部斜杠，如果您希望保留以前的默认行为（或 trailingSlash: "ignore"），请添加一个。

import { defineConfig } from "astro/config";

export default defineConfig({
  base: 'my-base',
  base: 'my-base/',
});

默认值已更改：`compressHTML`

在 Astro v2.x 中，只有当 compressHTML 被明确设置为 true 时，Astro 才会压缩您生成的 HTML。默认值为 false。

Astro v3.0 现在默认压缩生成的 HTML。

我应该怎么做？

您现在可以从配置中移除 compressHTML: true，因为这是新的默认行为。

import { defineConfig } from "astro/config";

export default defineConfig({
  compressHTML: true
})

您现在必须设置 compressHTML: false 以选择退出 HTML 压缩。

默认值已更改：`scopedStyleStrategy`

在 Astro v2.x 中，scopedStyleStrategy 的默认值为 "where"。

Astro v3.0 引入了一个新的默认值："attribute"。默认情况下，样式现在使用 data-* 属性应用。

我应该怎么做？

要保留项目的当前样式作用域，请将配置文件更新为以前的默认值

import { defineConfig } from "astro/config";

export default defineConfig({
  scopedStyleStrategy: "where"
})

默认值已更改：`inlineStyleSheets`

在 Astro v2.x 中，所有项目样式表默认作为链接标签发送。您可以通过设置 build.inlineStylesheets 配置，选择每次都将其内联到 <style> 标签中（使用 "always"），或者只内联特定大小以下的样式表（使用 "auto"）。默认设置为 "never"。

Astro v3.0 将 inlineStyleSheets 的默认值更改为 "auto"。小于 ViteConfig.build.assetsInlineLimit（默认：4kb）的样式表默认内联。否则，项目样式将以外部样式表的形式发送。

我应该怎么做？

如果您想保留项目当前的表现，请将 build.inlineStylesheets 设置为之前的默认值 "never"

import { defineConfig } from "astro/config";

export default defineConfig({
   build: {
    inlineStylesheets: "never"
  }
})

默认值已更改：图像服务

在 Astro v2.x 中，Squoosh 是默认的图像处理服务。

Astro v3.0 现在将 Sharp 作为默认图像处理服务，并提供了使用 Squoosh 的配置选项。

我应该怎么做？

如果您希望继续使用 Squoosh 来转换图像，请使用以下内容更新您的配置

import { defineConfig, squooshImageService } from "astro/config";

export default defineConfig({
  image: {
    service: squooshImageService(),
  }
})

已更改：HTTP 请求方法的大小写

在 Astro v2.x 中，HTTP 请求方法使用小写函数名编写：get、post、put、all 和 del。

Astro v3.0 使用大写函数名，包括 DELETE 而不是 del。

我应该怎么做？

将所有函数重命名为对应的大写形式

get to GET
post to POST
put to PUT
all to ALL
del to DELETE

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

已更改：多 JSX 框架配置

在 Astro v2.x 中，您可以在同一个项目中使用多个 JSX 框架集成（React、Solid、Preact），而无需识别哪些文件属于哪个框架。

Astro v3.0 现在要求您在安装了多个 JSX 框架集成时，使用新的 include 和 exclude 集成配置选项来指定文件要使用的框架。这使得 Astro 能够更好地支持单框架使用，以及 React Fast Refresh 等高级功能。

我应该怎么做？

如果您在同一个项目中使用多个 JSX 框架，请将 include（以及可选的 exclude）设置为文件和/或文件夹的数组。可以使用通配符包含多个文件路径。

我们建议将通用框架组件放在同一个文件夹中（例如 /components/react/ 和 /components/solid/），以便更容易地指定你的 include，但这不是必需的：

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';

export default defineConfig({
  // Enable many frameworks to support all different kinds of components.
  // No `include` is needed if you are only using a single framework!
  integrations: [
    preact({
      include: ['**/preact/*']
    }),
    react({
      include: ['**/react/*']
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ]
});

已更改：`Astro.cookies.get(key)` 可以返回 `undefined`

在 Astro v2.x 中，Astro.cookies.get(key) 总是返回一个 AstroCookie 对象，即使该 cookie 不存在。要检查其是否存在，您需要使用 Astro.cookies.has(key)。

如果 cookie 不存在，Astro v3.0 会为 Astro.cookies.get(key) 返回 undefined。

我应该怎么做？

此更改不会破坏任何在使用 Astro.cookies.get(key) 之前检查 Astro.cookie 对象是否存在的代码，但现在不再需要这样做。

您可以安全地移除任何使用 has() 检查 Astro.cookies 值是否为 undefined 的代码。

if (Astro.cookies.has(id)) {
  const id = Astro.cookies.get(id)!;
}

const id = Astro.cookies.get(id);
if (id) {
}

已更改：以编程方式运行 Astro CLI

在 Astro v2.x 中，"astro" 包入口点直接导出并运行 Astro CLI。在实践中不建议以这种方式运行 Astro。

Astro v3.0 从入口点移除了 CLI，并导出了新的实验性 JavaScript API 集，包括 dev()、build()、preview() 和 sync()。

我应该怎么做？

要以编程方式运行 Astro CLI，请使用新的实验性 JavaScript API

import { dev, build } from "astro";

// Start the Astro dev server
const devServer = await dev();
await devServer.stop();

// Build your Astro project
await build();

已更改：内部 Astro API 入口点导出路径

在 Astro v2.x 中，您可以从 astro/internal/* 和 astro/runtime/server/* 导入内部 Astro API。

Astro v3.0 移除了这两个入口点，转而支持现有的 astro/runtime/* 入口点。此外，还添加了一个新的 astro/compiler-runtime 导出，用于编译器特定的运行时代码。

我应该怎么做？

这些是 Astro 内部 API 的入口点，不应影响您的项目。但如果您确实使用了这些入口点，请按如下所示进行更新

import 'astro/internal/index.js';
import 'astro/runtime/server/index.js';

import 'astro/server/index.js';
import 'astro/runtime/server/index.js';

import { transform } from '@astrojs/compiler';

const result = await transform(source, {
  internalURL: 'astro/runtime/server/index.js',
  internalURL: 'astro/compiler-runtime',
  // ...
});

功能升级

将图像升级到 v3

在 Astro v3.0 中，astro:assets 不再是一个实验性标志。

<Image /> 现在是一个内置组件，并且之前的 @astrojs/image 集成已被移除。

这些以及其他伴随的 Astro 图像使用更改可能会在您将 Astro 项目从早期版本升级时导致一些破坏性更改。

请根据需要遵循以下说明，将 Astro v2.x 项目升级到 v3.0。

从 `experimental.assets` 升级

如果您之前已为 astro:assets 启用了实验性标志，您将需要更新您的项目以适应 Astro v3.0，该版本现在默认包含资产特性。

移除 `experimental.assets` 标志

移除实验性标志

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true
  }
});

如果需要，请更新您的 src/env.d.ts 文件，将 astro/client-image 引用替换为 astro/client

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

移除 `~/assets` 导入别名

此导入别名不再默认包含在 astro:assets 中。如果您曾将此别名与实验性资产一起使用，则必须将其转换为相对文件路径，或者创建您自己的导入别名。

---
import rocket from '~/assets/rocket.png';
import rocket from '../../assets/rocket.png';
---

为 Cloudflare、Deno、Vercel Edge 和 Netlify Edge 添加简单的资产支持

Astro v3.0 允许 astro:assets 在 Cloudflare、Deno、Vercel Edge 和 Netlify Edge 中无错误地工作，这些环境不支持 Astro 内置的 Squoosh 和 Sharp 图像优化。请注意，Astro 在这些环境中不执行任何图像转换和处理。然而，您仍然可以享受使用 astro:assets 的其他好处，包括没有累积布局偏移 (CLS)、强制的 alt 属性以及一致的创作体验。

如果您之前由于这些限制而避免使用 astro:assets，那么现在可以毫无问题地使用它们。您可以配置无操作图像服务以明确选择此行为

import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
});

决定图像存储位置

请参阅图像指南，帮助您决定图片存储位置。您可能希望利用 astro:assets 带来的额外灵活性，以新的方式存储图像。例如，现在可以使用标准 Markdown ![alt](src) 语法在 Markdown、MDX 和 Markdoc 中引用项目 src/ 中的相对图像。

更新现有 `<img>` 标签

以前，导入图像会返回一个简单的 string，其中包含图像路径。现在，导入的图像资源符合以下签名

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

您必须更新任何现有 <img> 标签（包括 UI 框架组件中的图像）的 src 属性，您还可以更新从导入图像中现在可用的其他属性。

---
import rocket from '../images/rocket.svg';
---
<img src={rocket} width="250" height="250" alt="A rocketship in space." />

<img src={rocket.src} width={rocket.width} height={rocket.height} alt="A rocketship in space." />

更新您的 Markdown、MDX 和 Markdoc 文件

现在可以使用标准 Markdown ![alt](src) 语法在 Markdown、MDX 和 Markdoc 中引用项目 src/ 中的相对图像。

这允许您将图像从 public/ 目录移动到项目 src/，在那里它们将进行处理和优化。您在 public/ 中的现有图像和远程图像仍然有效，但不会由 Astro 的构建过程进行优化。

# My Markdown Page

<!-- Local images now possible! -->
![A starry night sky.](../../images/stars.png)

<!-- Keep your images next to your content! -->
![A starry night sky.](./stars.png)

如果您需要对图像属性进行更多控制，我们建议使用 .mdx 文件格式，除了 Markdown 语法外，它还允许您包含 Astro 的 <Image /> 组件或 JSX <img /> 标签。使用 MDX 集成为 Astro 添加 MDX 支持。

移除 `@astrojs/image`

如果您在 Astro v2.x 中使用了图像集成，请完成以下步骤

移除 @astrojs/image 集成。

您必须移除该集成，方法是卸载它，然后从您的 astro.config.mjs 文件中将其移除。

import { defineConfig } from 'astro/config';
import image from '@astrojs/image';

export default defineConfig({
  integrations: [
    image(),
  ]
})

更新类型（如果需要）。

如果您在 src/env.d.ts 中为 @astrojs/image 配置了特殊类型，如果您的 v3 升级没有为您完成此步骤，您可能需要将它们改回默认的 Astro 类型。
src/env.d.ts
```
 /// <reference types="@astrojs/image/client" />
 /// <reference types="astro/client" />
```
同样，如有必要，更新 tsconfig.json
tsconfig.json
```
{
  "compilerOptions": {
    "types": ["@astrojs/image/client"]
    "types": ["astro/client"]
  }
}
```
迁移任何现有的 <Image /> 组件。

将所有 import 语句从 @astrojs/image/components 更改为 astro:assets，以便使用新的内置 <Image /> 组件。

移除任何当前不支持的图像资源属性的组件属性。

例如，aspectRatio 不再受支持，因为它现在是从 width 和 height 属性自动推断的。
src/components/MyComponent.astro
```
---
import { Image } from '@astrojs/image/components';
import { Image } from 'astro:assets';
import localImage from '../assets/logo.png';
const localAlt = 'The Astro Logo';
---

<Image
  src={localImage}
  width={300}
  aspectRatio="16:9"
  alt={localAlt}
/>
```
选择默认图像服务。

Sharp 现在是 astro:assets 的默认图像服务。如果您想使用 Sharp，则无需配置。

如果您更喜欢使用 Squoosh 来转换图像，请使用以下 image.service 选项更新您的配置
astro.config.mjs
```
import { defineConfig, squooshImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});
```

更新内容集合模式

您现在可以在 frontmatter 中使用相对于当前文件夹的路径来声明内容集合条目（例如博客文章的封面图像）的关联图像。

内容集合的新 image 助手允许您使用 Zod 验证图像元数据。了解更多关于如何在内容集合中使用图像的信息。

Astro v3.0 中的图像导入导航

在 Astro v3.0 中，如果您必须保留旧的图像导入行为并需要图像 URL 的字符串表示，请在导入图像时在其路径末尾添加 ?url。例如

---
import Sprite from '../assets/logo.svg?url';
---

<svg>
  <use xlink:href={Sprite + '#cart'} />
</svg>

这种方法确保您获得 URL 字符串。请记住，在开发过程中，Astro 使用 src/ 路径，但在构建时，它会生成哈希路径，例如 /_astro/cat.a6737dd3.png。

如果您更喜欢直接使用图像对象本身，可以访问 .src 属性。此方法最适用于管理图像尺寸以优化核心 Web 指标和防止 CLS 等任务。

如果您正在过渡到新的导入行为，结合使用 ?url 和 .src 方法可能是实现无缝图像处理的正确选择。

将视图过渡升级到 v3

在 Astro v3.0 中，视图过渡不再是实验性标志。

如果您在 Astro 2.x 中**未**启用此实验性标志，则不会对您的项目造成任何重大更改。新的视图过渡 API 对您现有的代码没有影响。

如果您以前使用过实验性视图过渡，那么在您将 Astro 项目从早期版本升级时，可能会有一些重大更改。

请根据需要按照以下说明将**配置了 experimental.viewTransitions: true 的 Astro v2.x 项目**升级到 v3.0。

从 `experimental.viewTransitions` 升级

如果您之前已为视图过渡启用了实验性标志，则需要更新您的项目以适应 Astro v3.0，该版本现在默认允许视图过渡。

移除 `experimental.viewTransitions` 标志

移除实验性标志

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
   viewTransitions: true
  }
});

更新导入源

<ViewTransitions /> 组件已从 astro:components 移至 astro:transitions。请更新项目中所有出现的导入源。

---
import { ViewTransitions } from "astro:components astro:transitions"
---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ViewTransitions />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

更新 `transition:animate` 指令

已更改： transition:animate 值 morph 已重命名为 initial。此外，这不再是默认动画。如果未指定 transition:animate 指令，您的动画现在将默认为 fade。

将所有 morph 动画重命名为 initial。
src/components/MyComponent.astro
```
<div transition:name="name" transition:animate="morph initial" />
```
要保留以前默认使用 morph 的任何动画，请明确添加 transition:animate="initial"
src/components/MyComponent.astro
```
<div transition:name="name" transition:animate="initial" />
```
您可以安全地移除任何明确设置为 fade 的动画。这现在是默认行为
src/components/MyComponent.astro
```
<div transition:name="name" transition:animate="fade" />
```

已添加： Astro 还支持新的 transition:animate 值 none。此值可用于页面的 <html> 元素，以禁用整个页面的动画全页过渡。这只会覆盖页面元素上没有动画指令的**默认动画行为**。您仍然可以为单个元素设置动画，并且这些特定动画将发生。

您现在可以禁用单个页面上的所有默认过渡，仅对明确使用 transition:animate 指令的元素进行动画处理
```
<html transition:animate="none">
  <head></head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>
```

更新事件名称

事件 astro:load 已重命名为 astro:page-load。请更新项目中所有出现的此事件名称。

<script>
document.addEventListener('astro:load astro:page-load', runSetupLogic);
</script>

事件 astro:beforeload 已重命名为 astro:after-swap。请更新项目中所有出现的此事件名称。

<script>
document.addEventListener('astro:beforeload astro:after-swap', setDarkMode);
</script>

社区资源

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

已知问题

目前没有已知问题。

贡献社区赞助

升级到 Astro v3

升级 Astro

Astro v3.0 实验性标志已移除

Astro v3.0 破坏性变更

已移除：对 Node 16 的支持

我应该怎么做？

已移除：对 TypeScript 4 的支持

我应该怎么做？

已移除：@astrojs/image

我应该怎么做？

已移除：<Markdown /> 组件

我应该怎么做？

已移除：已弃用的 1.x API

我应该怎么做？

已移除：服务器代码中 Web API 的部分垫片

我应该怎么做？

已移除：内容集合 schema 中 astro:content 的 image

我应该怎么做？

已移除：0.14 版之前的 Shiki 主题名称

我应该怎么做？

已移除：class:list 特性

我应该怎么做？

已移除：将 class:list 作为 prop 传递

我应该怎么做？

已移除：camelCase CSS 变量的 kebab-case 转换

我应该怎么做？

已移除：getStaticPaths() 返回值的自动扁平化

我应该怎么做？

已迁移：astro check 现在需要一个外部包

我应该怎么做？

已弃用：build.excludeMiddleware 和 build.split

我应该怎么做？

已弃用：markdown.drafts

我应该怎么做？

已弃用：在端点中返回简单对象

我应该怎么做？

默认值已更改：tsconfig.json 预设中的 verbatimModuleSyntax

我应该怎么做？

默认值已更改：端口 3000

我应该怎么做？

默认值已更改：import.meta.env.BASE_URL trailingSlash

我应该怎么做？

默认值已更改：compressHTML

我应该怎么做？

默认值已更改：scopedStyleStrategy

我应该怎么做？

默认值已更改：inlineStyleSheets

我应该怎么做？

默认值已更改：图像服务

我应该怎么做？

已更改：HTTP 请求方法的大小写

我应该怎么做？

已更改：多 JSX 框架配置

我应该怎么做？

已更改：Astro.cookies.get(key) 可以返回 undefined

我应该怎么做？

已更改：以编程方式运行 Astro CLI

我应该怎么做？

已更改：内部 Astro API 入口点导出路径

我应该怎么做？

功能升级

将图像升级到 v3

从 experimental.assets 升级

移除 experimental.assets 标志

移除 ~/assets 导入别名

为 Cloudflare、Deno、Vercel Edge 和 Netlify Edge 添加简单的资产支持

决定图像存储位置

更新现有 <img> 标签

更新您的 Markdown、MDX 和 Markdoc 文件

移除 @astrojs/image

更新内容集合模式

Astro v3.0 中的图像导入导航

将视图过渡升级到 v3

从 experimental.viewTransitions 升级

移除 experimental.viewTransitions 标志

更新导入源

更新 transition:animate 指令

更新事件名称

社区资源

已知问题

已移除：`@astrojs/image`

已移除：`<Markdown />` 组件

已移除：内容集合 schema 中 `astro:content` 的 `image`

已移除：`class:list` 特性

已移除：将 `class:list` 作为 prop 传递

已移除：`getStaticPaths()` 返回值的自动扁平化

已迁移：`astro check` 现在需要一个外部包

已弃用：`build.excludeMiddleware` 和 `build.split`

已弃用：`markdown.drafts`

默认值已更改：tsconfig.json 预设中的 `verbatimModuleSyntax`

默认值已更改：端口 `3000`

默认值已更改：import.meta.env.BASE_URL `trailingSlash`

默认值已更改：`compressHTML`

默认值已更改：`scopedStyleStrategy`

默认值已更改：`inlineStyleSheets`

已更改：`Astro.cookies.get(key)` 可以返回 `undefined`

从 `experimental.assets` 升级

移除 `experimental.assets` 标志

移除 `~/assets` 导入别名

更新现有 `<img>` 标签

移除 `@astrojs/image`

从 `experimental.viewTransitions` 升级

移除 `experimental.viewTransitions` 标志

更新 `transition:animate` 指令