Question

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

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

升级 Astro

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

• npm
• pnpm
• Yarn

# 升级到 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

需要继续吗？

升级 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 或更高版本。

1. 使用以下命令检查 Node 本地版本：

   node -v

2. 查看你的 部署环境 的文档，以确认它们是否支持 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 图像升级建议 了解完整的详情！

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 实例。

src/components/MyAstroComponent.astro

---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 迁移指南
• 废弃的脚本/样式类型：请参阅 0.26 迁移指南

移除：服务器代码中 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 帮助程序 来验证图像。

src/content/config.ts

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 元素替换为普通数组。

src/components/MyAstroComponent.astro

<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 的代码。

src/components/MyAstroComponent.astro

---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，以防止丢失样式。例如：

src/components/MyAstroComponent.astro

<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 适配器配置选项 替换了这些构建配置选项，以执行相同的任务：edgeMiddleware 和 functionPerRoute。

我应该怎么做？

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

astro.config.mjs

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


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

astro.config.mjs

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 对象。

endpoint.json.ts

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

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

endpoint.json.ts

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 语法。

src/components/MyAstroComponent.astro

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

虽然我们建议保持此设置项为启用状态并（像上面展示的那样）使用 import type 来导入类型，如果出现了任何问题，你可以通过在 tsconfig.json 中设置 verbatimModuleSyntax: false 来禁用它。

tsconfig.json

{
  "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 后添加一个斜杠。

astro.config.mjs

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，因为这是新的默认行为。

astro.config.mjs

import { defineConfig } from "astro/config";


export default defineConfig({  compressHTML: true
})

你现在必须设置 compressHTML: false 来禁用 HTML 压缩。

默认值改变：scopedStyleStrategy

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

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

我应该怎么做？

为了保留你项目的当前 样式作用域，请修改配置文件为以前的默认值：

astro.config.mjs

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

astro.config.mjs

import { defineConfig } from "astro/config";


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

默认值改变：图像服务

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

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

我应该怎么做？

注意

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

pnpm add sharp

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

astro.config.mjs

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

endpoint.ts

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

社区资源

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

已知问题

目前没有已知的问题。

Upgrade Guides