升级到 Astro v3

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

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

升级 Astro

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

# 升级到 Astro v3.x
npm install astro@latest

# 示例：升级 React 和 Tailwind 集成
npm install @astrojs/react@latest @astrojs/tailwind@latest

# 升级到 Astro v3.x
pnpm add astro@latest

# 示例：升级 React 和 Tailwind 集成
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

# 升级到 Astro v3.x
yarn add astro@latest

# 示例：升级 React 和 Tailwind 集成
yarn add @astrojs/react@latest @astrojs/tailwind@latest

:::note[需要继续吗？]升级 Astro 到最新版本后，你可能不需要对你的项目做任何更改！

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

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

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

// 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。
```
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 图像升级建议了解完整的详情！

// astro.config.mjs
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 的 <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 迁移指南 (EN)
废弃的脚本/样式类型：请参阅 0.26 迁移指南 (EN)

移除：服务器代码中 Web API 的不完整垫片（shim）

在 Astro v2.x 中，Astro 在服务器渲染代码中提供了例如像 document 或 localStorage 这样的 Web APIs 的不完整垫片（shim，类似 polyfill）。这些垫片经常实现不完整并且不可靠。

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

我应该怎么做？

如果你在服务器渲染的组件中使用 Web 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(),
   }),
});

移除：pre-0.14 Shiki 主题名称

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

Astro v3.0 删除了原始名称，而采用了重命名的主题名称。

我应该怎么做？

如果你的 Astro 项目使用了以下任何主题，请将它们重命名为更新后的名称：

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 现在直接使用 clsx 来处理 class:list，它不支持去重和 Set 值。

我应该怎么做？

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

<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 变量被渲染。

---
// src/components/MyAstroComponent.astro
const myValue = "red"
---
<!-- 输入 -->
<div style={{ "--myValue": myValue }}></div>

<!-- 输出 (Astro 2.x) -->
<div style="--my-value:var(--myValue);--myValue:red"></div>
<!-- 输出 (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 来确保你返回的是展平的一维数组。

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

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

在 Astro v2.x 中，默认情况下包含了 astro check，并且它的依赖项被打包在 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 适配器配置选项 (EN) 替换了这些构建配置选项，以执行相同的任务：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 属性手动过滤页面。

废弃：在端点（endpoints）中返回简单对象

在 Astro v2.x 中，端点（endpoints）可以返回一个简单的对象，它会被转换为一个 JSON 响应。

Astro v3.0 废弃了这种行为，而是直接返回一个 Response 对象。

我应该怎么做？

更新你的端点（endpoints），直接返回一个 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 默认是关闭的，在 strict 预设中它的 TypeScript 4.x 等价设置项 importsNotUsedAsValues 是启用的。

在 Astro v3.0 中，所有预设都启用了 verbatimModuleSyntax。

我应该怎么做？

这个选项使得类型导入必须使用 import type 语法。

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

虽然我们建议保持此设置项为启用状态并（像上面展示的那样）使用 import 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 中，除非 trailingSlash 被设置为 never，否则 import.meta.env.BASE_URL 总是被设置成以斜杠 / 结尾的 base。也就是说默认情况下如果 base 不是以斜杠结尾的，Astro 会帮你添加一个。

Astro v3.0 中的 import.meta.env.BASE_URL 默认情况下不再给 base 添加斜杠，也不会在设置 trailingSlash: "ignore" 时添加斜杠。trailingSlash: "always" 和 trailingSlash: "never" 的行为保持不变。

我应该怎么做？

如果你的 base 已经以斜杠结尾，或你的 trailingSlash 设置为 always 或 never，则不需要更改。

如果你的 base 不以斜杠结尾并且你希望 import.meta.env.BASE_URL 与以前保持一致，请在 base 后添加一个斜杠。

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 中，默认情况下，所有项目样式表都作为 link 标签输出。你可以通过设置为 "always" 使它们总是内联到 <style> 标签中，或者设置为 "auto" 再通过 build.inlineStylesheets 设置项来仅内联小于某个大小的样式表。默认设置曾经为 "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。

我应该怎么做？

:::note当使用像 pnpm 这样的严格包管理器时，即使 Sharp 已经是 Astro 的依赖项，你也可能需要手动安装 Sharp 到你的项目中：

pnpm add sharp

:::

如果你希望继续使用 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 改为 GET
post 改为 POST
put 改为 PUT
all 改为 ALL
del 改为 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/），以便更容易地指定你的包含内容，但这不是必需的：

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({
  // 启用多个框架来支持所有不同类型的组件。
  // 如果你只使用一个 JSX 框架，则不需要 `include`！
  integrations: [
    preact({
      include: ['**/preact/*'],
    }),
    react({
      include: ['**/react/*'],
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ],
});

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

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

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

我应该怎么做？

这个修改不会影响任何在调用 Astro.cookies.get(key) 之前用 Astro.cookies.has(key) 检查 cookie 是否存在的代码，但现在不再需要检查。

你可以安全的删除任何使用 has() 来检查 cookie 是否存在的代码：

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";

// 启动 Astro 开发服务器
const devServer = await dev();
await devServer.stop();

// 构建 Astro 项目
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:assets 不再是 Astro v3.0 中的实验性标志。

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

当你从早期版本升级你的 Astro 项目时，这些和其他伴随的更改，可能会导致一些破坏性的变化。

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

从 `experimental.assets` 升级

如果你之前启用了 astro:assets 的实验性标志，你需要更新你的项目到 Astro v3.0，它现在默认包含了 assets 功能。

移除 `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> 标签的 src 属性（包括任何 UI 框架组件中的图像），你也可以更新从导入的图像中获得的其他属性。

---
import rocket from '../images/rocket.svg';
---
<img src={rocket} width="250" height="250" alt="太空中的火箭飞船。" />

<img src={rocket.src} width={rocket.width} height={rocket.height} alt="太空中的火箭飞船。" />

更新你的 Markdown, MDX, 和 Markdoc 文件

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

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

# 我的 Markdown 页面

<!-- 现在可以使用本地图像 -->
![繁星点点的夜空](../../images/stars.png)

<!-- 将你的图像放在你的内容旁边！ -->
![繁星点点的夜空](./stars.png)

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

移除 `@astrojs/image`

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

移除 @astrojs/image 集成。

你必须通过卸载并从你的 astro.config.mjs 文件中删除它，来移除集成 (EN)。

// 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 的默认类型。
```
 /// <reference types="@astrojs/image/client" />
 /// <reference types="astro/client" />
```
同样地，如果需要的话，更新 tsconfig.json：
```
{
	"compilerOptions": {
	  "types": ["@astrojs/image/client"]
	  "types": ["astro/client"]
	}
}
```
迁移任何现有的 <Image /> 组件。

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

移除任何当前不支持的图像属性。

例如，aspectRatio 不再支持，因为它现在可以从 width 和 height 属性中自动推断出来。
```
---
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 选项更新你的配置：
```
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 属性。这种方法非常适合用于管理图像尺寸以适应 Core Web Vitals 指标和避免 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，因为现在 Astro 默认支持视图过渡动画。

移除 `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。

<div transition:name="name" transition:animate="morph initial" />

为了保持任何以前默认使用 morph 的动画，显式添加 transition:animate="initial"。
```
<div transition:name="name" transition:animate="initial" />
```
你可以安全地删除任何显式设置为 fade 的动画。这是现在的默认行为：
```
<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。在你的项目中重命名所有 astro:load 出现的地方。

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

事件 astro:beforeload 已重命名为 astro:after-swap。在你的项目中重命名所有 astro:beforeload 出现的地方。

<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 的不完整垫片（shim）

我应该怎么做？

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

我应该怎么做？

移除：pre-0.14 Shiki 主题名称

我应该怎么做？

移除：class:list 功能

我应该怎么做？

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

我应该怎么做？

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

我应该怎么做？

移除：自动展平 getStaticPaths() 的返回值

我应该怎么做？

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

我应该怎么做？

废弃：build.excludeMiddleware 和 build.split

我应该怎么做？

废弃：markdown.drafts

我应该怎么做？

废弃：在端点（endpoints）中返回简单对象

我应该怎么做？

默认值改变：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` 指令