升级到 Astro v2

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

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

升级 Astro

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

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

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

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

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

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

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

Astro v2.0 破坏性更改

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

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

移除：对 Node 14 的支持

Node 14 计划在 2023 年 4 月结束其生命周期。

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

我应该怎么做？

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

使用以下命令检查本地版本的 Node：
Terminal window
```
node -v
```
如果你的本地开发环境需要升级，安装 Node.
查看你的部署环境的文档，以确认它们是否支持 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.site 访问时，你在 astro.config.mjs 中设置的 site 始终带有末尾斜线。

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

我应该怎么做？

在astro.config.mjs中，为site设置的 URL 添加末尾斜线。

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 版本中，Astro 使用 markdown.extendDefaultPlugins 在添加你自己的 Markdown 插件时重新启用 Astro 的默认插件。

Astro v2.0 完全移除了这个配置选项，因为它已经变为默认配置。

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

我应该怎么做？

在你的配置中移除 extendDefaultPlugins。这已经成为 Astro v2.0 的默认配置，你可以删除这一行，无需任何替换。

import { defineConfig } from 'astro/config';

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

新增： `gfm` 和 `smartypants`

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

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

我应该怎么做？

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

markdown.gfm: false 禁用 GitHub 风格的 Markdown
markdown.smartypants: false 禁用 SmartyPants

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 风格的 Markdown
mdx.smartypants 用于在 MDX 中启用或禁用 SmartyPants

我应该怎么做？

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

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

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

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

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

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

新增：更多的 MDX 配置选项以匹配 Markdown

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

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 订阅项列表。现在已弃用此用法，并将最终被移除。

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

我应该怎么做？

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

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 文件：

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 中已不再可用。

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

如果你在 v1.x 版本中使用了这个特性，我们推荐使用 MDX 集成，它允许你将组件和 JSX 表达式与 Markdown 语法结合起来。

移除：`Astro.resolve()`

在 v0.24 版本中，Astro 废弃了 Astro.resolve() 这个用于获取浏览器中可能引用的资源解析后的 URL 的方法。

Astro v2.0 完全移除了这个选项。在你的代码中的 Astro.resolve() 将会引起错误。

我应该怎么做？

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

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

<img src={imageUrl} />

移除：`Astro.fetchContent()`

在 v0.26 版本中，Astro 废弃了用于从本地 Markdown 文件中获取数据的 Astro.fetchContent() 方法。

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

我应该怎么做？

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

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

移除：`Astro.canonicalURL`

在 v1.0 版本中，Astro 废弃了用于构建规范 URL 的 Astro.canonicalURL 方法。

Astro v2.0 完全移除了这个选项。在你的代码中使用 Astro.canonicalURL 会引发错误。

我应该怎么做？

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

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

更新：Vite 4

Astro v2.0 从 Vite 3 升级到 Vite 4，该版本于 2022 年 12 月发布。

我应该怎么做？

在你的代码中应该不需要做任何更改！我们已经在 Astro 内部处理了大部分的升级工作；然而，一些微妙的 Vite 行为在不同版本之间可能仍然有所变化。

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

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

从 astro.config.mjs 文件中删除以下实验性标志：

import { defineConfig } from 'astro/config';

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

这些功能现在已默认可用：

内容集合，用于以类型安全的方式管理你的 Markdown 和 MDX 文件。

在使用 SSR 时，将个别页面预渲染为静态 HTML，以提高速度和缓存能力。详见配置个别路由。
重新设计的错误消息覆盖层。

已知问题

目前没有已知的问题。

升级到 Astro v2

升级 Astro

Astro v2.0 破坏性更改

移除：对 Node 14 的支持

我应该怎么做？

保留：src/content/

我应该怎么做？

变更：Astro.site 末尾斜线

我应该怎么做？

变更：用于构建资源的 _astro/ 文件夹

我应该怎么做？

变更：Markdown 插件配置

移除：extendDefaultPlugins

我应该怎么做？

新增： gfm 和 smartypants

我应该怎么做？

变更：MDX 插件配置

替换：extendPlugins 更改为 extendMarkdownConfig

我应该怎么做？

新增：更多的 MDX 配置选项以匹配 Markdown

我应该怎么做？

变更：插件对 frontmatter 的访问权限

我应该怎么做？

变更：RSS 配置

我应该怎么做？

变更：Svelte IDE 支持

我应该怎么做？

移除：legacy.astroFlavoredMarkdown

我应该怎么做？

移除：Astro.resolve()

我应该怎么做？

移除：Astro.fetchContent()

我应该怎么做？

移除：Astro.canonicalURL

我应该怎么做？

更新：Vite 4

我应该怎么做？

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

已知问题

保留：`src/content/`

变更：用于构建资源的 `_astro/` 文件夹

移除：`extendDefaultPlugins`

新增： `gfm` 和 `smartypants`

替换：`extendPlugins` 更改为 `extendMarkdownConfig`

移除：`legacy.astroFlavoredMarkdown`

移除：`Astro.resolve()`

移除：`Astro.fetchContent()`

移除：`Astro.canonicalURL`