旧版 v0.x 升级指南

本指南将帮助你升级 Astro v1 之前版本的重大变更。

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

# updates the astro dependency:
npm upgrade astro
# or, to update all dependencies:
npm upgrade

# updates the astro dependency:
pnpm upgrade astro
# or, to update all dependencies:
pnpm upgrade

# updates the astro dependency:
yarn upgrade astro
# or, to update all dependencies:
yarn upgrade

阅读下面的指南，了解主要亮点以及如何处理重大变更的说明。

Astro 1.0

Astro v1.0 引入了一些变更，在从 v0.x 和 v1.0-beta 版本迁移时需要注意。详见下文。

已更新：Vite 3

Astro v1.0 从 Vite 2 升级到了 Vite 3。我们已经在 Astro 内部为你处理了大部分升级工作；但是，版本之间的一些细微的 Vite 行为可能仍然会发生变化。如果遇到问题，请参阅官方的 Vite 迁移指南。

已弃用： `Astro.canonicalURL`

现在，你可以使用新的 Astro.url 辅助函数从当前页面/请求 URL 构建自己的规范 URL。

// Before:
const canonicalURL = Astro.canonicalURL;
// After:
const canonicalURL = new URL(Astro.url.pathname, Astro.site);

已更改：作用域 CSS 的特异性

现在，作用域 CSS 样式中的特异性将被保留。此更改将导致大多数作用域样式恰好优先于全局样式。但是，这种行为不再被明确保证。

从技术上讲，这是通过使用 :where() 伪类而不是直接在 Astro 的 CSS 输出中使用类来实现的。

让我们以 Astro 组件中的以下样式块为例

<style>
  div { color: red; } /* 0-0-1 specificity */
</style>

以前，Astro 会将其转换为以下 CSS，其特异性为 0-1-1 — 比源 CSS 的特异性更高

div.astro-XXXXXX { color: red; } /* 0-1-1 specificity */

现在，Astro 使用 :where() 包装类选择器，从而保持了编写时的特异性

div:where(.astro-XXXXXX) { color: red; } /* 0-0-1 specificity */

之前的特异性增加使得在 Astro 中将作用域样式与其他 CSS 文件或样式库（例如 Tailwind、CSS Modules、Styled Components、Stitches）结合起来变得困难。这一更改将使 Astro 的作用域样式能够与它们一致地工作，同时仍然保留防止样式应用到组件外部的专属边界。

已弃用：Markdown 中的组件和 JSX

默认情况下，Astro 不再支持在 Markdown 页面中使用组件或 JSX 表达式。为了获得长期支持，你应该迁移到 @astrojs/mdx 集成。

为了使迁移更容易，可以使用一个新的 legacy.astroFlavoredMarkdown 标志（在 v2.0 中已移除）来重新启用以前的 Markdown 功能。

将现有的 `.md` 文件转换为 `.mdx`

如果你不熟悉 MDX，可以按照以下步骤快速将现有的“Astro 风味 Markdown”文件转换为 MDX。随着你对 MDX 的了解加深，可以自由探索其他编写页面的方式！

安装 @astrojs/mdx 集成。
将你现有的 .md 文件扩展名更改为 .mdx

从 frontmatter 中移除任何 setup: 属性，并将任何导入语句写在 frontmatter 下方。

---
layout: '../../layouts/BaseLayout.astro'
setup: |
  import ReactCounter from '../../components/ReactCounter.jsx'
title: 'Migrating to MDX'
date: 2022-07-26
tags: ["markdown", "mdx", "astro"]
---
import ReactCounter from '../../components/ReactCounter.jsx'

# {frontmatter.title}

Here is my counter component, working in MDX:

<ReactCounter client:load />

更新任何当前返回 .md 文件的 Astro.glob() 语句，使其现在返回你的 .mdx 文件。

导入 .mdx 文件时返回的对象（包括使用 Astro.glob）与导入 .md 文件时返回的对象不同。但是，frontmatter、file 和 url 的工作方式完全相同。

更新任何使用 <Content /> 组件的地方，以在导入 MDX 时使用默认导出

---
// Multiple imports with Astro.glob
const mdxPosts = await Astro.glob('./posts/*.mdx');
---

{mdxPosts.map(Post => <Post.default />)}

---
// Import a single page
import { default as About } from './about.mdx';
---

<About />

在过渡到 MDX 期间，你可能希望启用 legacy.astroFlavoredMarkdown 标志（在 v2.0 中已移除）并同时包含 .md 和 .mdx 文件，这样即使在所有文件都转换完成之前，你的网站也能正常运行。以下是一种实现方法

---
const mdPosts = await Astro.glob('../pages/posts/*.md');
const mdxPosts = await Astro.glob('../pages/posts/*.mdx');
const allPosts = [...mdxPosts, ...mdPosts];
---

`<Markdown />` 组件已移除

Astro 的内置 <Markdown /> 组件已移至一个独立的包中。要继续使用此组件，你现在需要安装 @astrojs/markdown-component 并相应地更新你的导入。有关更多详细信息，请参阅 @astrojs/markdown 的 README。

迁移到 v1.0.0-beta

2022 年 4 月 4 日，我们发布了 Astro 1.0 Beta！ 🎉

如果你来自 v0.25 或更早的版本，请确保你已阅读并遵循下面的 v0.26 迁移指南，其中包含几个重大的破坏性更改。

Astro 的 v1.0.0-beta.0 版本不包含任何破坏性更改。以下是在 beta 期间引入的一些小更改。

已更改：RSS 源

现在应使用 @astrojs/rss 包生成 RSS 源，如我们的 RSS 指南中所述。

迁移到 v0.26

新的配置 API

我们的配置 API 经过重新设计，以解决过去一年中积累的一些明显的混淆点。大多数配置选项只是被移动或重命名，希望对大多数用户来说这是一个快速的更新。少数选项被更大幅度地重构，可能需要一些额外的更改。

.buildOptions.site 已被替换为 .site（你的部署域名）和一个新的 .base（你的部署子路径）选项。
.markdownOptions 已被替换为 .markdown，这是一个基本相似的配置对象，但有一些小的更改以简化 Markdown 配置。
.sitemap 已移至 @astrojs/sitemap 集成中。

如果你使用旧版配置运行 Astro，你将看到一条警告，其中包含有关如何更新的说明。有关升级的更多信息，请参阅我们更新的配置参考。

阅读 RFC0019 了解有关这些更改的更多背景信息。

新的 Markdown API

Astro v0.26 为你的内容发布了一个全新的 Markdown API。这包括三个主要面向用户的更改

你现在可以使用 ESM 导入直接 import/import() markdown 内容。
一个新的 Astro.glob() API，用于更轻松地进行 glob 导入（尤其是对于 Markdown）。
重大变更：Astro.fetchContent() 已被移除并由 Astro.glob() 替代
重大变更： Markdown 对象具有更新的接口。

// v0.25
let allPosts = Astro.fetchContent('./posts/*.md');
// v0.26+
let allPosts = await Astro.glob('./posts/*.md');

迁移时，请注意新的 Markdown 对象接口。例如，Frontmatter 已移至 .frontmatter 属性，因此像 post.title 这样的引用应更改为 post.frontmatter.title。

这应该能为 Markdown 用户解决许多问题，包括为大型网站带来一些不错的性能提升。

阅读 RFC0017 了解有关这些更改的更多背景信息。

新的默认脚本行为

Astro 组件中的 <script> 标签现在默认被构建、打包和优化。这完成了一项长期举措，使我们的 Astro 组件语法更加一致，与我们今天 <style> 标签的默认优化行为相匹配。

这包括一些需要注意的更改

重大变更： <script hoist> 是新的默认 <script> 行为。 hoist 属性已被移除。要使用新的默认行为，请确保 <script> 标签上没有其他属性。例如，如果你以前使用过 type="module"，请将其移除。
新的 <script is:inline> 指令，用于将 <script> 标签恢复到以前的默认行为（未构建、未打包、不受 Astro 影响）。
新的 <style is:inline> 指令，用于将样式标签内联在页面模板中（类似于以前的 <script> 行为）。
新的 <style is:global> 指令，用于在未来版本中替换 <style global>。

// v0.25
<script hoist type="module">
// v0.26+
<script>

有关完整详细信息，请参阅如何在 Astro 中使用客户端脚本。

阅读 RFC0016 了解有关这些更改的更多背景信息。

已更新的 `Astro.request` API

Astro.request 已从我们的自定义对象更改为标准的 Request 对象。这是使用更多 Web 标准 API 的项目的一部分，尤其是在涉及 SSR 的情况下。

这包括一些需要注意的更改

将 Astro.request 更改为 Request 对象。
将 Astro.request.params 移动到 Astro.params。
将 Astro.request.canonicalURL 移动到 Astro.canonicalURL。

阅读 RFC0018 了解有关这些更改的更多背景信息。

其他变更

改进 Astro.slots API 以支持向基于函数的插槽传递参数。这允许更符合人体工程学的实用程序组件接受回调函数作为子组件。
更新 CLI 输出格式，尤其是在错误报告方面。
更新 @astrojs/compiler，修复了一些与在 frontmatter 中使用 RegExp 相关的错误

迁移到 v0.25

Astro 集成

renderers 配置已被新的官方集成系统取代！这为 Astro 带来了一些非常令人兴奋的新功能。你可以阅读我们的使用集成指南，了解如何使用这个新系统的更多详情。

集成取代了我们最初的 renderers 概念，并为现有用户带来了一些重大变更和新默认值。这些更改将在下面介绍。

已移除：内置框架支持

以前，React、Preact、Svelte 和 Vue 默认都包含在 Astro 中。从 v0.25.0 开始，Astro 不再附带任何内置的渲染器。如果你的项目之前没有定义 renderers 配置项，你现在需要自己安装这些框架。

阅读我们的分步指南，了解如何为你当前使用的框架添加新的 Astro 集成。

已弃用：渲染器

新的集成系统取代了以前的 renderers 系统，包括 npm 上已发布的 @astrojs/renderer-* 包。从现在起，@astrojs/renderer-react 变成 @astrojs/react，@astrojs/renderer-vue 变成 @astrojs/vue，以此类推。

迁移方法：将 Astro 更新到 v0.25.0，然后使用包含过时 "renderers" 配置的旧配置文件运行 astro dev 或 astro build。你会立即看到一条通知，根据你当前的配置，告诉你需要对 astro.config.mjs 文件进行的确切更改。你也可以使用下表自己更新你的包。

更深入的指南，请阅读我们的分步指南，了解如何用新的 Astro 框架集成替换现有的渲染器。

# Install your new integrations and frameworks:
# (Read the full walkthrough: https://docs.astro.js.cn/en/guides/integrations-guide)
npm install @astrojs/lit lit
npm install @astrojs/react react react-dom

// Then, update your `astro.config.mjs` file:
// (Read the full walkthrough: https://docs.astro.js.cn/en/guides/integrations-guide)
import lit from '@astrojs/lit';
import react from '@astrojs/react';

export default {
  renderers: ['@astrojs/renderer-lit', '@astrojs/renderer-react'],
  integrations: [lit(), react()],
}

npm 上已弃用的渲染器	npm 上的 v0.25+ 集成
@astrojs/renderer-react	@astrojs/react
@astrojs/renderer-preact	@astrojs/preact
@astrojs/renderer-solid	@astrojs/solid-js
@astrojs/renderer-vue	@astrojs/vue
@astrojs/renderer-svelte	@astrojs/svelte

处理对等依赖

与旧的渲染器不同，集成不再将框架本身（“react”、“svelte”、“vue”等）标记为集成的直接依赖项。相反，你现在应该*除了*安装集成之外，还要安装你的框架包。

# Example: Install integrations and frameworks together
npm install @astrojs/react react react-dom

如果你在启动 Astro 时看到 "Cannot find package 'react'"（或类似）的警告，这意味着你需要将该包安装到你的项目中。有关更多信息，请参阅我们的故障排除指南中的关于对等依赖的说明。

如果你正在使用 npm 和 Node v16+，那么 npm 可能会自动为你处理这个问题，因为最新版本的 npm (v7+) 会自动为你安装这样的对等依赖项。在这种情况下，将像“react”这样的框架安装到你的项目中是一个可选但仍然推荐的步骤。

已更新：语法高亮

我们喜欢寻找那些“开箱即用”的合理默认值。为此，我们决定将 Shiki 作为我们新的默认语法高亮器。它预先配置了 github-dark 主题，在你的代码块中提供零配置高亮，无需额外的 CSS 类、样式表或客户端 JS。

查看我们新的语法高亮文档以获取完整详情。如果你更喜欢保留 Prism 作为你的语法高亮器，请在你的项目 markdown 配置中将 syntaxHighlight 选项设置为 'prism'。

`<Prism />` 组件有了新家

作为我们保持 Astro 核心尽可能精简的使命的一部分，我们已将内置的 Prism 组件从 astro/components 移出，并放入 @astrojs/prism 包中。你现在可以像这样从 @astrojs/prism 导入此组件

---
import { Prism } from '@astrojs/prism';
---

由于 @astrojs/prism 包仍然与 astro 核心捆绑在一起，你不需要安装任何新东西，也不需要将 Prism 添加为集成！但是请注意，我们确实计划在将来将 @astrojs/prism（以及 Prism 语法高亮功能）提取到一个独立的、可安装的包中。有关更多详情，请参阅 <Prism /> 组件 API 参考。

CSS 解析器升级

我们的内部 CSS 解析器已更新，并更好地支持高级 CSS 语法，如容器查询。对于大多数用户来说，这应该是一个几乎看不见的变化，但希望高级用户会喜欢新的 CSS 功能支持。

迁移到 v0.24

0.24 引入了一个新的*静态构建*策略，它改变了一些功能的行为。在以前的 Astro 版本中，这是一个可选的行为，通过一个选择性标志启用：--experimental-static-build。

为了顺利过渡，请注意以下更改，这些更改是迁移到这个新的构建引擎所必需的。你可以随时对你的代码库进行这些更改，以便提前准备好。

已弃用： `Astro.resolve()`

Astro.resolve() 允许你获取你可能想在浏览器中引用的资源的解析后 URL。这最常用于 <link> 和 <img> 标签中，以按需加载 CSS 文件和图片。不幸的是，由于 Astro 现在在*构建时*而不是在*渲染时*构建资源，这将不再起作用。你需要将你的资源引用升级到以下未来可用的选项之一

如何解析 CSS 文件

1. ESM 导入（推荐）

示例： import './style.css'; 何时使用： 如果你的 CSS 文件位于 src/ 目录内，并且你想要自动的 CSS 构建和优化功能。

使用 ESM 导入来向页面添加一些 CSS。Astro 会检测这些 CSS 导入，然后自动构建、优化并将 CSS 添加到页面中。这是从 Astro.resolve() 迁移并保留 Astro 提供的自动构建/打包功能的最简单方法。

---
// Example: Astro will include and optimize this CSS for you automatically
import './style.css';
---
<html><!-- Your page here --></html>

在任何支持 ESM 导入的地方，导入 CSS 文件都应该有效，包括

JavaScript 文件
TypeScript 文件
Astro 组件的 frontmatter
非 Astro 组件，如 React、Svelte 等

当使用此方法导入 CSS 文件时，任何 @import 语句也会被解析并内联到导入的 CSS 文件中。所有 url() 引用也会相对于源文件解析，并且任何 url() 引用的资源都将包含在最终的构建中。

2. 绝对 URL 路径

示例： <link href="/style.css"> 何时使用： 如果你的 CSS 文件位于 public/ 内，并且你希望自己创建 HTML link 元素。

你可以在组件模板中通过绝对 URL 路径引用 public/ 目录内的任何文件。如果你想自己控制页面上的 <link> 标签，这是一个很好的选择。但是，这种方法也跳过了 Astro 在你使用上述 import 方法时提供的 CSS 处理、打包和优化。

我们建议使用 import 方法而不是绝对 URL 方法，因为它默认提供了最佳的 CSS 性能和功能。

如何解析 JavaScript 文件

1. 绝对 URL 路径

示例： <script src="/some-external-script.js" /> 何时使用： 如果你的 JavaScript 文件位于 public/ 内。

你可以在 Astro 组件模板中通过绝对 URL 路径引用 public/ 目录内的任何文件。对于外部脚本，这是一个很好的默认选项，因为它让你自己控制页面上的 <script> 标签。

请注意，这种方法跳过了 Astro 在你使用下述 import 方法时提供的 JavaScript 处理、打包和优化。然而，对于已经单独于 Astro 发布和压缩的任何外部脚本，这可能是首选。如果你的脚本是从外部源下载的，那么这种方法可能更可取。

2. 通过 <script hoist> 进行 ESM 导入

示例： <script hoist>import './some-external-script.js';</script> 何时使用： 如果你的外部脚本位于 src/ 内并且它支持 ESM 模块类型。

在 Astro 模板中的 <script hoist> 元素内使用 ESM 导入，Astro 将把 JavaScript 文件包含在你的最终构建中。Astro 会检测这些 JavaScript 客户端导入，然后自动构建、优化并将 JavaScript 添加到页面中。这是从 Astro.resolve() 迁移并保留 Astro 提供的自动构建/打包功能的最简单方法。

<script hoist>
  import './some-external-script.js';
</script>

请注意，Astro 会将此外部脚本与你其余的客户端 JavaScript 捆绑在一起，并在 type="module" 脚本上下文中加载它。一些较旧的 JavaScript 文件可能不是为 module 上下文编写的，在这种情况下，它们可能需要更新才能使用此方法。

如何解析图片及其他资源

1. 绝对 URL 路径（推荐）

示例： <img src="/penguin.png"> 何时使用： 如果你的资源位于 public/ 内。

如果你将图片放在 public/ 内，你可以安全地在组件模板中直接通过绝对 URL 路径引用它们。这是你今天可以使用的最简单的引用资源的方式，并且推荐给大多数刚开始使用 Astro 的用户。

2. ESM 导入

示例： import imgUrl from './penguin.png' 何时使用： 如果你的资源位于 src/ 目录内，并且你想要自动优化功能，如文件名哈希。

这在任何 JavaScript 或 Astro 组件内都有效，并返回到最终图片的解析后 URL。一旦你有了解析后的 URL，你就可以在组件模板中的任何地方使用它。

---
// Example: Astro will include this image file in your final build
import imgUrl from './penguin.png';
---
<img src={imgUrl} />

与 Astro 处理 CSS 的方式类似，ESM 导入允许 Astro 自动为你执行一些简单的构建优化。例如，任何在 src/ 内通过 ESM 导入的资源（例如：import imgUrl from './penguin.png'）都会自动对其文件名进行哈希处理。这可以让你在服务器上更积极地缓存文件，从而提高用户性能。未来，Astro 可能会添加更多类似的优化。

提示： 如果你不喜欢静态 ESM 导入，Astro 也支持动态 ESM 导入。我们只在你偏好这种语法时推荐此选项：<img src={(await import('./penguin.png')).default} />。

已弃用： `<script>` 默认处理

以前，所有 <script> 元素都会从最终的 HTML 输出中读取并自动处理和捆绑。此行为不再是默认的。从 0.24 开始，你必须通过 hoist 属性选择加入 <script> 元素处理。对于提升的模块，type="module" 也是必需的。

<script>
  // Will be rendered into the HTML exactly as written!
  // ESM imports will not be resolved relative to the file.
</script>
<script type="module" hoist>
  // Processed! Bundled! ESM imports work, even to npm packages.
</script>

迁移到 v0.23

缺少 Sass 错误

Preprocessor dependency "sass" not found. Did you install it?

为了减少 npm 安装大小，我们已将 Sass 移至可选依赖项。如果你在项目中使用 Sass，请确保运行 npm install sass --save-dev 将其保存为依赖项。

已弃用：未转义的 HTML

在 Astro v0.23+ 中，表达式中未转义的 HTML 内容现已弃用。在未来的版本中，表达式中的内容将被转义字符串，以防止意外的 HTML 注入。

<h1>{title}</h1> <!-- <h1>Hello <strong>World</strong></h1> -->
<h1>{title}</h1> <!-- <h1>Hello &lt;strong&gt;World&lt;/strong&gt;</h1> -->

要继续注入未转义的 HTML，你现在可以使用 set:html。

<h1>{title}</h1>
<h1 set:html={title} />

为避免包装元素，set:html 可以与 <Fragment> 一起使用。

<h1>{title}!</h1>
<h1><Fragment set:html={title}>!</h1>

你还可以使用 set:text 来防止意外的 HTML 注入。

<h1 set:text={title} /> <!-- <h1>Hello &lt;strong&gt;World&lt;/strong&gt;</h1> -->

迁移到 v0.21

Vite

从 v0.21 开始，Astro 使用 Vite 构建。因此，写在 snowpack.config.mjs 中的配置应移至 astro.config.mjs。

// @ts-check

/** @type {import('astro').AstroUserConfig} */
export default {
  renderers: [],
  vite: {
    plugins: [],
  },
};

要了解有关配置 Vite 的更多信息，请访问其配置指南。

Vite 插件

在 Astro v0.21+ 中，Vite 插件可以在 astro.config.mjs 中配置。

import { imagetools } from 'vite-imagetools';

export default {
  vite: {
    plugins: [imagetools()],
  },
};

要了解有关 Vite 插件的更多信息，请访问其插件指南。

Vite 对渲染器的更改

在 Astro v0.21+ 中，插件现在应使用 viteConfig()。

import { svelte } from '@sveltejs/vite-plugin-svelte';

export default {
  name: '@astrojs/renderer-svelte',
  client: './client.js',
  server: './server.js',
  snowpackPlugin: '@snowpack/plugin-svelte',
  snowpackPluginOptions: { compilerOptions: { hydratable: true } },
  viteConfig() {
    return {
      optimizeDeps: {
        include: ['@astrojs/renderer-svelte/client.js', 'svelte', 'svelte/internal'],
        exclude: ['@astrojs/renderer-svelte/server.js'],
      },
      plugins: [
        svelte({
          emitCss: true,
          compilerOptions: { hydratable: true },
        }),
      ],
    };
  },
}

要了解有关 Vite 插件的更多信息，请访问其插件指南。

别名

在 Astro v0.21+ 中，可以在 tsconfig.json 中添加导入别名。

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["src/components/*"]
    }
  }
}

导入中的文件扩展名

在 Astro v0.21+ 中，文件需要通过其实际扩展名引用，与磁盘上的完全一致。在此示例中，Div.tsx 需要被引用为 Div.tsx，而不是 Div.jsx。

import Div from './Div.jsx' // Astro v0.20
import Div from './Div.tsx' // Astro v0.21

这一变化同样适用于编译到 CSS 的文件，如 Div.scss

<link rel="stylesheet" href={Astro.resolve('./Div.css')}>
<link rel="stylesheet" href={Astro.resolve('./Div.scss')}>

已移除：Frontmatter 中的组件

以前，你可以在 Astro Frontmatter 内部创建迷你 Astro 组件，使用 JSX 语法而不是 Astro 的组件语法。这一直有点像是一个 hack，但在新的编译器中，它变得无法支持。我们希望在未来的 Astro 版本中通过一个不同的、非 JSX 的 API 重新引入此功能。

要迁移到 v0.21+，请将所有 JSX Astro 组件（即在另一个组件的 frontmatter 内部创建的任何 Astro 组件）转换为独立的组件。

样式变更

Autoprefixer

Autoprefixer 默认不再运行。要启用它

安装最新版本 (npm install autoprefixer)
在你的项目根目录下创建一个 postcss.config.cjs 文件，内容如下
```
module.exports = {
  plugins: {
    autoprefixer: {},
  },
};
```

Tailwind CSS

确保你已经安装了 PostCSS。这在以前的版本中是可选的，但现在是必需的

安装最新版本的 postcss (npm install -D postcss)
在你的项目根目录下创建一个 postcss.config.cjs 文件，内容如下
```
module.exports = {
  plugins: {
    tailwindcss: {},
  },
};
```
更多信息，请阅读 Tailwind CSS 文档

已知问题

置顶导入

在 Astro v0.21+ 中，引入了一个 bug，该 bug 要求组件内部的 import 语句必须位于 frontmatter 的顶部。

---
import Component from '../components/Component.astro'
const whereShouldIPutMyImports = "on top!"
---

贡献社区赞助