跳转到内容

升级到 Astro v3

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

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

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

Terminal window
# 升级到 Astro v3.x
npm install astro@latest
# 示例:升级 React 和 Tailwind 集成
npm install @astrojs/react@latest @astrojs/tailwind@latest

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

段落标题 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 破坏性更改

Astro v3.0 包含了一些破坏性更改,以及一些之前已经弃用的功能的移除。如果你的项目在升级到 v3.0 后无法正常工作,请查看本指南,了解所有破坏性更改的概述以及如何更新你的代码库的说明。

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

移除:对 Node 16 的支持

段落标题 移除:对 Node 16 的支持

Node 16 计划在 2023 年 9 月达到其生命周期终点。

Astro v3.0 完全放弃对 Node 16 的支持,以便所有 Astro 用户都能利用 Node 的更现代化的功能。

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

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

    Terminal window
    node -v
  2. 查看你的 部署环境 的文档,以确认它们是否支持 Node 18。

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

    .nvmrc
    18.14.1

移除:对 TypeScript 4 的支持

段落标题 移除:对 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。

Terminal window
npm install typescript@latest --save-dev

在 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(),
]
})

在 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

段落标题 移除:已废弃的 1.x API

在 Astro v1.x 中,Astro 废弃了对最初的配置选项以及 <style global><script hoist> 的支持。但为了向后兼容,它们依旧可用。

Astro v3.0 完全删除了这些已弃用的 API。你应该使用正式被支持的配置选项以及现代的 <style is:global><script>

如果你正在继续使用 v1.x API,请改用每个功能的新 API:

移除:服务器代码中 Web API 的不完整垫片(shim)

段落标题 移除:服务器代码中 Web API 的不完整垫片(shim)

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

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

如果你在服务器渲染的组件中使用 Web API,你需要把使用了的地方改成根据运行平台选择性调用或使用 client:only 客户端指令.

移除:内容集合 schema 中来自 astro:contentimage

段落标题 移除:内容集合 schema 中来自 astro:content 的 image

在 Astro v2.x 中,内容集合 API 废弃了来自 astro:contentimage 导出,用于在你的内容集合 schema 中使用。

Astro v3.0 完全删除了这个导出。

如果你正在使用 astro:content 中废弃的 image(),请删除它,因为它已经不存在了。请通过 来自 schemaimage 帮助程序 来验证图像。

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 主题名称

段落标题 移除: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 功能

段落标题 移除: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 传递

段落标题 移除:将 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 转换

段落标题 移除:对于 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() 的返回值

段落标题 移除:自动展平 getStaticPaths() 的返回值

在 Astro v2.x 中,getStaticPaths() 的返回值会自动展平,以允许返回一个二维数组而不会出错。

Astro v3.0 移除了对 getStaticPaths() 返回值的自动展平。

如果你返回的是一个二维数组而不是一个(预期的)一维对象数组,则应该使用 .flatMap.flat 来确保你返回的是展平的一维数组。

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

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

段落标题 移动: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/checktypescript 安装到你的项目中。

废弃:build.excludeMiddlewarebuild.split

段落标题 废弃:build.excludeMiddleware 和 build.split

在 Astro v2.x 中,build.excludeMiddlewarebuild.split 用于在 SSR 模式下使用适配器时更改特定文件的产出方式。

Astro v3.0 用新的 SSR 适配器配置选项 替换了这些构建配置选项,以执行相同的任务:edgeMiddlewarefunctionPerRoute

更新 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
}),
});

在 Astro v2.x 中,markdown.drafts 配置允许你在运行开发服务器时拥有草稿页面,但在生产环境中不会构建。

Astro v3.0 废弃了这个功能,而是使用内容集合的方法来处理草稿页面,通过手动过滤来实现,这样可以更好地控制这个功能。

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

废弃:在端点(endpoints)中返回简单对象

段落标题 废弃:在端点(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

段落标题 默认值改变: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

段落标题 默认值改变:端口 3000

在 Astro v2.x 中,默认情况下,Astro 运行在 3000 端口上。

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

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

默认值改变:import.meta.env.BASE_URL trailingSlash

段落标题 默认值改变: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 设置为 alwaysnever,则不需要更改。

如果你的 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

段落标题 默认值改变: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

段落标题 默认值改变: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

段落标题 默认值改变: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。

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

astro.config.mjs
import { defineConfig, squooshImageService } from "astro/config";
export default defineConfig({
image: {
service: squooshImageService(),
}
})

修改:HTTP 请求方法案例

段落标题 修改:HTTP 请求方法案例

在 Astro v2.x 中,HTTP 请求方法 使用小写函数名称编写:getpostputalldel

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 框架配置

段落标题 修改:多个 JSX 框架配置

在 Astro v2.x 中,你可以在同一个项目中使用多个 JSX 框架集成(React、Solid、Preact)而不需要指定哪些文件属于哪个框架。

Astro v3.0 现在要求你在有多个 JSX 框架集成时,使用新的 includeexclude 集成配置选项来指定你的文件使用哪个框架。这使得 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.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 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 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:assets 不再是 Astro v3.0 中的实验性标志。

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

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

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

experimental.assets 升级

段落标题 从 experimental.assets 升级

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

移除 experimental.assets 标志
段落标题 移除 experimental.assets 标志

移除实验性标志:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
assets: true
}
});

如果需要,还可以更新你的 src/env.d.ts 文件,将 astro/client-image 引用替换为 astro/client

src/env.d.ts
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />
移除~/assets 导入别名
段落标题 移除~/assets 导入别名

这个导入别名不再默认包含在 astro:assets 中。如果你之前使用这个别名,你必须将它们转换为相对文件路径,或者 创建你自己的导入别名

src/pages/posts/post-1.astro
---
import rocket from '~/assets/rocket.png';
import rocket from '../../assets/rocket.png';
---
为 Cloudflare, Deno, Vercel Edge 和 Netlify Edge 添加简单的资源支持
段落标题 为 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,现在你可以在没有问题的情况下使用它们。你可以配置无操作图像服务来显式地选择这种行为:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
image: {
service: {
entrypoint: 'astro/assets/services/noop'
}
}
});

决定在哪里存储你的图像

段落标题 决定在哪里存储你的图像

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

以前,导入图像将返回一个简单的 string,其中包含图像的路径。现在,导入的图像资源与以下签名相匹配:

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

你必须更新任何现有 <img> 标签的 src 属性(包括任何 UI 框架组件中的图像),你也可以更新从导入的图像中获得的其他属性。

src/components/MyComponent.astro
---
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, MDX, 和 Markdoc 文件

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

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

src/pages/posts/post-1.md
# 我的 Markdown 页面
<!-- 现在可以使用本地图像 -->
![繁星点点的夜空](../../images/stars.png)
<!-- 将你的图像放在你的内容旁边! -->
![繁星点点的夜空](./stars.png)

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

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

  1. 移除 @astrojs/image 集成。

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

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import image from '@astrojs/image';
    export default defineConfig({
    integrations: [
    image(),
    ]
    })
  2. 更新类型(如果需要的话)。

    如果你在 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"]
    }
    }
  3. 迁移任何现有的 <Image /> 组件。

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

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

    例如,aspectRatio 不再支持,因为它现在可以从 widthheight 属性中自动推断出来。

    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}
    />
  4. 选择一个默认图像服务。

    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 中导航图像导入

在 Astro v3.0 中,如果你需要保留旧的图像导入方式,并要求图像的 URL 以字符串表示,你可以在导入图像时在图像路径的末尾添加 ?url。例如:

src/pages/blog/MyImages.astro
---
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

段落标题 升级视图过渡动画到 v3

在 Astro v3.0 中,视图过渡动画不再是实验性的。

如果你 没有 在 Astro 2.x 中启用此实验性标志,则不会对你的项目造成任何破坏性的更改。新的视图过渡动画 API 不会影响你现有的代码。

如果你之前使用了实验性的视图过渡动画,那么从早期版本升级你的 Astro 项目时可能会有一些破坏性的更改。

请根据以下说明适当地升级 使用 experimental.viewTransitions: true 配置的 Astro v2.x 项目 到 v3.0。

experimental.viewTransitions 升级

段落标题 从 experimental.viewTransitions 升级

如果你之前启用了视图过渡动画的实验性标志,那么你需要更新你的项目到 Astro v3.0,因为现在 Astro 默认支持视图过渡动画。

移除 experimental.viewTransitions 标志
段落标题 移除 experimental.viewTransitions 标志

移除实验性标志:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
viewTransitions: true
}
});

<ViewTransitions /> 组件被从 astro:components 移动到了 astro:transitions。请在你的项目中更新导入来源。

src/layouts/BaseLayout.astro
---
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 指令

改变: transition:animate 的值 morph 已重命名为 initial。此外,这不再是默认的动画。如果没有指定 transition:animate 指令,则你的动画现在默认为 fade

  1. 重命名任何 morph 动画为 initial

    src/components/MyComponent.astro
    <div transition:name="name" transition:animate="morph initial" />
  2. 为了保持任何以前默认使用 morph 的动画,显式添加 transition:animate="initial"

    src/components/MyComponent.astro
    <div transition:name="name" transition:animate="initial" />
  3. 你可以安全地删除任何显式设置为 fade 的动画。这是现在的默认行为:

    src/components/MyComponent.astro
    <div transition:name="name" transition:animate="fade" />

添加: Astro 还支持一个新的 transition:animate 值,none。这个值可以在页面的 <html> 元素上使用,以禁用整个页面上的动画过渡。这只会覆盖页面元素上默认的动画行为,而不是动画指令。你仍然可以在单个元素上设置动画,这些特定的动画将会发生。

  1. 你现在可以在单个页面上禁用所有默认的过渡动画,只对显式使用 transition:animate 指令的元素进行动画:

    <html transition:animate="none">
    <head></head>
    <body>
    <h1>Hello world!</h1>
    </body>
    </html>

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

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

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

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

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

目前没有已知的问题。