升级到 Astro v2

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

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

升级 Astro

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

npm

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

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

pnpm

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

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

Yarn

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

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

Astro v2.0 破坏性变更

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

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

已移除：对 Node 14 的支持

Node 14 计划于 2023 年 4 月终止支持 (End of Life)。

Astro v2.0 完全放弃了对 Node 14 的支持，以便所有 Astro 用户都能利用 Node 的更现代化的功能。

我应该怎么做？

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

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

   node -v

   如果你的本地开发环境需要升级，请安装 Node。

2. 请查阅你的部署环境的文档，以确认其是否支持 Node 16。

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

保留： src/content/

Astro v2.0 现在包含了用于将 Markdown 和 MDX 文件组织成内容集合的 Collections API。该 API 将 src/content/ 保留为一个特殊文件夹。

我应该怎么做？

请重命名任何已有的 src/content/ 文件夹以避免冲突。该文件夹（如果存在）现在只能用于内容集合。

已更改：Astro.site 的尾部斜杠

在 v1.x 中，Astro 确保你在 astro.config.mjs 中设置的 site URL 在通过 Astro.site 访问时始终带有尾部斜杠。

Astro v2.0 不再修改 site 的值。Astro.site 将使用确切定义的值，如果需要，必须明确指定尾部斜杠。

我应该怎么做？

在 astro.config.mjs 中，为你设置的 site URL 添加一个尾部斜杠。

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  site: 'https://example.com/',
});

已更改：构建产物的 _astro/ 文件夹

在 v1.x 中，构建产物被输出到不同位置，包括 assets/、chunks/ 以及构建输出的根目录。

Astro v2.0 将所有构建输出产物的位置移动并统一到了一个新的 _astro/ 文件夹。

• 目录dist/

  • 目录_astro

    • client.9218e799.js
    • index.df3f880e0.css

你可以使用新的 build.assets 配置选项来控制此位置。

我应该怎么做？

如果你的部署平台配置依赖于这些产物的位置，请更新它。

已更改：Markdown 插件配置

已移除：extendDefaultPlugins

在 v1.x 中，当你添加自己的 Markdown 插件时，Astro 使用 markdown.extendDefaultPlugins 来重新启用 Astro 的默认插件。

Astro v2.0 完全移除了这个配置选项，因为它的行为现在是默认的。

在你的 Markdown 配置中应用 remark 和 rehype 插件将不再禁用 Astro 的默认插件。无论是否配置了自定义的 remarkPlugins 或 rehypePlugins，GitHub-Flavored Markdown 和 Smartypants 现在都会被应用。

我应该怎么做？

请在你的配置中移除 extendDefaultPlugins。这现在是 Astro v2.0 的默认行为，你可以直接删除这行，无需任何替换。

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    extendDefaultPlugins,
  }
});

已添加：gfm 和 smartypants

在 v1.x 中，你可以通过设置 markdown.extendDefaultPlugins: false 来选择禁用 Astro 的两个默认 Markdown 插件（GitHub-Flavored Markdown 和 SmartyPants）。

Astro v2.0 用独立的布尔选项替换了 markdown.extendDefaultPlugins: false，以分别控制每个 Astro 内置的默认 Markdown 插件。这些选项默认启用，并且可以独立设置为 false。

我应该怎么做？

移除 extendDefaultPlugins: false，并添加标志来单独禁用每个插件。

• markdown.gfm: false 禁用 GitHub-Flavored Markdown
• markdown.smartypants: false 禁用 SmartyPants

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    extendDefaultPlugins: false,
    smartypants: false,
    gfm: false,
  }
});

已更改：MDX 插件配置

已替换：extendPlugins 更改为 extendMarkdownConfig

在 v1.x 中，MDX 集成的 extendPlugins 选项管理你的 MDX 文件应如何继承你的 Markdown 配置：全部 Markdown 配置 (markdown)，或仅 Astro 的默认插件 (default)。

Astro v2.0 将由 mdx.extendPlugins 控制的行为替换为三个新的、可独立配置的选项，这些选项默认值为 true

• mdx.extendMarkdownConfig 用于继承全部或不继承你的 Markdown 配置
• mdx.gfm 用于在 MDX 中启用或禁用 GitHub-Flavored Markdown
• mdx.smartypants 用于在 MDX 中启用或禁用 SmartyPants

我应该怎么做？

在你的配置中删除 extendPlugins: 'markdown'。这现在是默认行为。

astro.config.mjs

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

export default defineConfig({
  integrations: [
    mdx({
      extendPlugins: 'markdown',
    }),
  ],
});

将 extendPlugins: 'defaults' 替换为 extendMarkdownConfig: false，并为 GitHub-Flavored Markdown 和 SmartyPants 添加单独的选项，以在 MDX 中单独启用这些默认插件。

astro.config.mjs

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

export default defineConfig({
  integrations: [
    mdx({
      extendPlugins: 'defaults',
      extendMarkdownConfig: false,
      smartypants: true,
      gfm: true,
    }),
  ],
});

已添加：更多与 Markdown 匹配的 MDX 配置选项

Astro v2.0 现在允许你在 MDX 集成配置中单独设置每个可用的 Markdown 配置选项（drafts 除外）。

astro.config.mjs

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

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      remarkPlugins: [remarkPlugin2],
      gfm: false,
    })
  ]
});

我应该怎么做？

重新审视你的 Markdown 和 MDX 配置，并将你现有的配置与新的可用选项进行比较。

已更改：插件对 frontmatter 的访问

在 v1.x 中，remark 和 rehype 插件无法访问用户的 frontmatter。Astro 将插件的 frontmatter 与你文件的 frontmatter 合并，而不会将文件的 frontmatter 传递给你的插件。

Astro v2.0 通过 frontmatter 注入，让 remark 和 rehype 插件可以访问用户的 frontmatter。这允许插件作者修改用户现有的 frontmatter，或根据其他属性计算新属性。

我应该怎么做？

检查你编写的任何 remark 和 rehype 插件，看看它们的行为是否已改变。请注意，data.astro.frontmatter 现在是完整的 Markdown 或 MDX 文档的 frontmatter，而不再是一个空对象。

已更改：RSS 配置

在 v1.x 中，Astro 的 RSS 包允许你使用 items: import.meta.glob(...) 来生成 RSS feed 项目列表。此用法现已弃用，并最终将被移除。

Astro v2.0 为 items 属性引入了一个 pagesGlobToRssItems() 包装器。

我应该怎么做？

导入 pagesGlobToRssItems() 帮助函数，然后用它包装你现有的包含 import.meta.glob() 的函数。

src/pages/rss.xml.js

import rss, {
  pagesGlobToRssItems
} from '@astrojs/rss';

export async function get(context) {
  return rss({
    items: await pagesGlobToRssItems(
      import.meta.glob('./blog/*.{md,mdx}'),
    ),
  });
}

已更改：Svelte IDE 支持

如果你正在使用@astrojs/svelte 集成，Astro v2.0 要求你的项目中有一个 svelte.config.js 文件。这是提供 IDE 自动补全所必需的。

我应该怎么做？

在你的项目根目录下添加一个 svelte.config.js 文件

svelte.config.js

import { vitePreprocess } from '@astrojs/svelte';

export default {
  preprocess: vitePreprocess(),
};

对于新用户，在运行 astro add svelte 时，此文件将自动添加。

已移除：legacy.astroFlavoredMarkdown

在 v1.0 中，Astro 将旧的 Astro-Flavored Markdown（也称为 Markdown 中的组件）移至一个旧版功能。

Astro v2.0 完全移除了 legacy.astroFlavoredMarkdown 选项。在 .md 文件中导入和使用组件将不再有效。

我应该怎么做？

移除这个旧版标志。它在 Astro 中已不再可用。

astro.config.mjs

export default defineConfig({
  legacy: {
    astroFlavoredMarkdown: true,
  },
})

如果你在 v1.x 中使用此功能，我们建议使用 MDX 集成，它允许你将组件和 JSX 表达式与 Markdown 语法结合使用。

已移除：Astro.resolve()

在 v0.24 中，Astro 弃用了 Astro.resolve()，该 API 用于获取你可能想在浏览器中引用的资源的解析后 URL。

Astro v2.0 完全移除了此选项。在你的代码中使用 Astro.resolve() 将导致错误。

我应该怎么做？

请改用 import 来解析资源路径。例如：

src/pages/index.astro

---
import 'style.css';
import imageUrl from './image.png';
---

<img src={imageUrl} />

已移除：Astro.fetchContent()

在 v0.26 中，Astro 弃用了 Astro.fetchContent()，该 API 用于从本地 Markdown 文件中获取数据。

Astro v2.0 完全移除了此选项。在你的代码中使用 Astro.fetchContent() 将导致错误。

我应该怎么做？

使用 Astro.glob() 来获取 Markdown 文件，或转换为内容集合功能。

src/pages/index.astro

---
const allPosts = await Astro.glob('./posts/*.md');
---

已移除：Astro.canonicalURL

在 v1.0 中，Astro 弃用了 Astro.canonicalURL，该 API 用于构建规范 URL。

Astro v2.0 完全移除了此选项。在你的代码中使用 Astro.canonicalURL 将导致错误。

我应该怎么做？

使用 Astro.url 来构建规范 URL。

src/pages/index.astro

---
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
---

已更新：Vite 4

Astro v2.0 从 Vite 3 升级到 2022 年 12 月发布的 Vite 4。

我应该怎么做？

你的代码应该无需任何更改！我们在 Astro 内部为你处理了大部分升级工作；但是，一些微妙的 Vite 行为在版本之间可能仍然会发生变化。

如果遇到问题，请参考官方的 Vite 迁移指南。

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

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

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    contentCollections: true,
    prerender: true,
    errorOverlay: true,
  },
})

这些功能现在已默认可用

• 内容集合作为一种具有类型安全性的方式来管理你的 Markdown 和 MDX 文件。
• 在使用 SSR 时将单个页面预渲染为静态 HTML，以提高速度和可缓存性。
• 重新设计的错误消息浮层。

已知问题

目前没有已知问题。