升级到 Astro v2

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

¥This guide will help you migrate from Astro v1 to Astro v2.

需要将旧项目升级到 v1？看看我们的较旧的迁移指南。

¥Need to upgrade an older project to v1? See our older migration guide.

升级 Astro

¥Upgrade Astro

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

¥Update your project’s version of Astro to the latest version using your package manager. If you’re using Astro integrations, please also update those to the latest version.

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

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

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

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

# 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 Breaking Changes

Astro v2.0 包含一些重大更改，并删除了一些以前弃用的功能。如果你的项目在升级到 v2.0 后未按预期工作，请查看本指南，了解所有重大更改的概述以及有关如何更新代码库的说明。

¥Astro v2.0 includes some breaking changes, as well as the removal of some previously deprecated features. If your project doesn’t work as expected after upgrading to v2.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase.

请参阅变更日志了解完整的发行说明。

¥See the changelog for full release notes.

已删除：支持 Node 14

¥Removed: Support for Node 14

Node 14 计划于 2023 年 4 月达到生命周期终点。

¥Node 14 is scheduled to reach its End of Life in April 2023.

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

¥Astro v2.0 drops Node 14 support entirely, so that all Astro users can take advantage of Node’s more modern features.

我应该怎么办？

¥What should I do?

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

¥Check that both your development environment and your deployment environment are using Node 16.12.0 or later.

Check your local version of Node using:
终端窗口
```
node -v
```
If your local development environment needs upgrading, install Node.
Check your deployment environment’s own documentation to verify that they support Node 16.

You can specify Node 16.12.0 for your Astro project either in a dashboard configuration setting, or a .nvmrc file.

保留：`src/content/`

¥Reserved: src/content/

Astro v2.0 现在包含 Collections API，用于将 Markdown 和 MDX 文件组织到内容集合中。该 API 保留 src/content/ 作为特殊文件夹。

¥Astro v2.0 now includes the Collections API for organizing your Markdown and MDX files into content collections. This API reserves src/content/ as a special folder.

我应该怎么办？

¥What should I do?

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

¥Rename an existing src/content/ folder to avoid conflicts. This folder, if it exists, can now only be used for content collections.

改变：`Astro.site` 尾部斜杠

¥Changed: Astro.site trailing slash

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

¥In v1.x, Astro ensured the URL you set as site in astro.config.mjs always had a trailing slash when accessed using Astro.site.

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

¥Astro v2.0 no longer modifies the value of site. Astro.site will use the exact value defined, and a trailing slash must be specified if desired.

我应该怎么办？

¥What should I do?

在 astro.config.mjs 中，向 site 中设置的 URL 添加尾部斜杠。

¥In astro.config.mjs, add a trailing slash to the URL set in site.

import { defineConfig } from 'astro/config';

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

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

¥Changed: _astro/ folder for build assets

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

¥In v1.x, assets were built to various locations, including assets/, chunks/, and to the root of the build output.

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

¥Astro v2.0 moves and unifies the location of all build output assets to a new _astro/ folder.

Directorydist/
- Directory_astro
  - client.9218e799.js
  - index.df3f880e0.css

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

¥You can control this location with the new build.assets configuration option.

我应该怎么办？

¥What should I do?

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

¥Update your deployment platform configuration if it relies on the location of these assets.

改变：Markdown 插件配置

¥Changed: Markdown plugin configuration

已删除：`extendDefaultPlugins`

¥Removed: extendDefaultPlugins

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

¥In v1.x, Astro used markdown.extendDefaultPlugins to re-enable Astro’s default plugins when adding your own Markdown plugins.

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

¥Astro v2.0 removes this configuration option entirely because its behavior is now the default.

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

¥Applying remark and rehype plugins in your Markdown configuration no longer disables Astro’s default plugins. GitHub-Flavored Markdown and Smartypants are now applied whether or not custom remarkPlugins or rehypePlugins are configured.

我应该怎么办？

¥What should I do?

删除配置中的 extendDefaultPlugins。现在这是 Astro 在 v2.0 中的默认行为，你可以删除此行而不进行任何替换。

¥Remove extendDefaultPlugins in your configuration. This is now Astro’s default behavior in v2.0, and you can delete this line without any replacement.

import { defineConfig } from 'astro/config';

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

添加：`gfm` 和 `smartypants`

¥Added: gfm and smartypants

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

¥In v1.x, you could choose to disable both of Astro’s default Markdown plugins (GitHub-Flavored Markdown and SmartyPants) by setting markdown.extendDefaultPlugins: false.

Astro v2.0 用单独的布尔选项取代了 markdown.extendDefaultPlugins: false，以单独控制每个 Astro 内置的默认 Markdown 插件。这些默认情况下处于启用状态，并且可以独立设置为 false。

¥Astro v2.0 replaces markdown.extendDefaultPlugins: false with separate Boolean options to individually control each of Astro’s built-in default Markdown plugins. These are enabled by default and can be set to false independently.

我应该怎么办？

¥What should I do?

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

¥Remove extendDefaultPlugins: false and add the flags to disable each plugin individually instead.

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 插件配置

¥Changed: MDX plugin configuration

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

¥Replaced: extendPlugins changed to extendMarkdownConfig

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

¥In v1.x, the MDX integration’s extendPlugins option managed how your MDX files should inherit your Markdown configuration: all your Markdown configuration (markdown), or Astro’s default plugins only (default).

Astro v2.0 用三个新的、可独立配置的选项取代了 mdx.extendPlugins 控制的行为，默认情况下为 true：

¥Astro v2.0 replaces the behavior controlled by mdx.extendPlugins with three new, independently-configurable options that are true by default:

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

我应该怎么办？

¥What should I do?

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

¥Delete extendPlugins: 'markdown' in your configuration. This is now the default behavior.

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 中单独启用这些默认插件。

¥Replace extendPlugins: 'defaults' with extendMarkdownConfig: false and add the separate options for GitHub-Flavored Markdown and SmartyPants to enable these default plugins individually in 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

¥Added: More MDX config options to match Markdown

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

¥Astro v2.0 allows you to now individually set every available Markdown configuration option (except drafts) separately in your MDX integration configuration.

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

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

我应该怎么办？

¥What should I do?

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

¥Revisit your Markdown and MDX configuration and compare your existing config with the new options available.

改变：插件访问前言

¥Changed: Plugin access to frontmatter

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

¥In v1.x, remark and rehype plugins did not have access to user frontmatter. Astro merged plugin frontmatter with your file’s frontmatter, without passing the file frontmatter to your plugins.

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

¥Astro v2.0 gives remark and rehype plugins access to user frontmatter via frontmatter injection. This allows plugin authors to modify a user’s existing frontmatter, or compute new properties based on other properties.

我应该怎么办？

¥What should I do?

检查你编写的任何评论和 rehype 插件，看看它们的行为是否发生了变化。请注意，data.astro.frontmatter 现在是完整的 Markdown 或 MDX 文档的 frontmatter，而不是空对象。

¥Check any remark and rehype plugins you have written to see whether their behavior has changed. Note that data.astro.frontmatter is now the complete Markdown or MDX document’s frontmatter, rather than an empty object.

改变：RSS 配置

¥Changed: RSS Configuration

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

¥In v1.x, Astro’s RSS package allowed you to use items: import.meta.glob(...) to generate a list of RSS feed items. This usage is now deprecated and will eventually be removed.

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

¥Astro v2.0 introduces a pagesGlobToRssItems() wrapper to the items property.

我应该怎么办？

¥What should I do?

导入，然后使用 pagesGlobToRssItems() 辅助程序封装包含 import.meta.glob() 的现有函数。

¥Import, then wrap your existing function containing import.meta.glob() with the pagesGlobToRssItems() helper.

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

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

改变：Svelte IDE 支持

¥Changed: Svelte IDE support

如果你使用 @astrojs/svelte 整合，Astro v2.0 需要你的项目中有 svelte.config.js 文件。这是提供 IDE 自动补齐功能所必需的。

¥Astro v2.0 requires a svelte.config.js file in your project if you are using the @astrojs/svelte integration. This is needed to provide IDE autocompletion.

我应该怎么办？

¥What should I do?

将 svelte.config.js 文件添加到项目的根目录：

¥Add a svelte.config.js file to the root of your project:

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

export default {
  preprocess: vitePreprocess(),
};

对于新用户，运行 astro add svelte 时会自动添加该文件。

¥For new users, this file will be added automatically when running astro add svelte.

已删除：`legacy.astroFlavoredMarkdown`

¥Removed: legacy.astroFlavoredMarkdown

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

¥In v1.0, Astro moved the old Astro-Flavored Markdown (also known as Components in Markdown) to a legacy feature.

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

¥Astro v2.0 removes the legacy.astroFlavoredMarkdown option completely. Importing and using components in .md files will no longer work.

我应该怎么办？

¥What should I do?

删除这个旧标志。Astro 中不再提供此功能。

¥Remove this legacy flag. It is no longer available in Astro.

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

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

¥If you were using this feature in v1.x, we recommend using the MDX integration which allows you to combine components and JSX expressions with Markdown syntax.

已删除：`Astro.resolve()`

¥Removed: Astro.resolve()

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

¥In v0.24, Astro deprecated Astro.resolve() for getting resolved URLs to assets that you might want to reference in the browser.

Astro v2.0 完全删除了这个选项。代码中的 Astro.resolve() 将导致错误。

¥Astro v2.0 removes this option entirely. Astro.resolve() in your code will cause an error.

我应该怎么办？

¥What should I do?

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

¥Resolve asset paths using import instead. For example:

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

<img src={imageUrl} />

已删除：`Astro.fetchContent()`

¥Removed: Astro.fetchContent()

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

¥In v0.26, Astro deprecated Astro.fetchContent() for fetching data from your local Markdown files.

Astro v2.0 完全删除了这个选项。代码中的 Astro.fetchContent() 将导致错误。

¥Astro v2.0 removes this option entirely. Astro.fetchContent() in your code will cause an error.

我应该怎么办？

¥What should I do?

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

¥Use Astro.glob() to fetch Markdown files, or convert to the Content Collections feature.

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

已删除：`Astro.canonicalURL`

¥Removed: Astro.canonicalURL

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

¥In v1.0, Astro deprecated Astro.canonicalURL for constructing a canonical URL.

Astro v2.0 完全删除了这个选项。代码中的 Astro.canonicalURL 将导致错误。

¥Astro v2.0 removes this option entirely. Astro.canonicalURL in your code will cause an error.

我应该怎么办？

¥What should I do?

使用 Astro.url 构造规范 URL。

¥Use Astro.url to construct a canonical URL.

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

已更新：Vite 4

¥Updated: Vite 4

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

¥Astro v2.0 upgrades from Vite 3 to Vite 4, released in December 2022.

我应该怎么办？

¥What should I do?

你的代码无需更改！我们已经在 Astro 内为你处理了大部分升级；然而，一些微妙的 Vite 行为在不同版本之间仍可能会发生变化。

¥There should be no changes to your code necessary! We’ve handled most of the upgrade for you inside of Astro; however, some subtle Vite behaviors may still change between versions.

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

¥Refer to the official Vite Migration Guide if you run into trouble.

Astro v2.0 实验标志已删除

¥Astro v2.0 Experimental Flags Removed

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

¥Remove the following experimental flags from astro.config.mjs:

import { defineConfig } from 'astro/config';

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

这些功能现在默认可用：

¥These features are now available by default:

内容集合作为一种类型安全管理 Markdown 和 MDX 文件的方法。
将各个页面预渲染为静态 HTML 当使用 SSR 来提高速度和缓存能力时。
重新设计的错误消息叠加层。

已知的问题

¥Known Issues

目前没有已知问题。

¥There are currently no known issues.

升级到 Astro v2

升级 Astro

Astro v2.0 重大变更

已删除：支持 Node 14

我应该怎么办？

保留：src/content/

我应该怎么办？

改变：Astro.site 尾部斜杠

我应该怎么办？

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

我应该怎么办？

改变：Markdown 插件配置

已删除：extendDefaultPlugins

我应该怎么办？

添加：gfm 和 smartypants

我应该怎么办？

改变：MDX 插件配置

已替换：extendPlugins 更改为 extendMarkdownConfig

我应该怎么办？

添加：更多 MDX 配置选项以匹配 Markdown

我应该怎么办？

改变：插件访问前言

我应该怎么办？

改变：RSS 配置

我应该怎么办？

改变：Svelte IDE 支持

我应该怎么办？

已删除：legacy.astroFlavoredMarkdown

我应该怎么办？

已删除：Astro.resolve()

我应该怎么办？

已删除：Astro.fetchContent()

我应该怎么办？

已删除：Astro.canonicalURL

我应该怎么办？

已更新：Vite 4

我应该怎么办？

Astro v2.0 实验标志已删除

已知的问题

保留：`src/content/`

改变：`Astro.site` 尾部斜杠

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

已删除：`extendDefaultPlugins`

添加：`gfm` 和 `smartypants`

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

已删除：`legacy.astroFlavoredMarkdown`

已删除：`Astro.resolve()`

已删除：`Astro.fetchContent()`

已删除：`Astro.canonicalURL`