从 Gatsby 迁移
以下是一些关键概念和迁移策略,帮助你开始。使用我们的其他文档和我们的 Discord 社区 继续进行!
Gatsby 和 Astro 之间的关键相似性
Section titled “Gatsby 和 Astro 之间的关键相似性”Gatsby 和 Astro 共享一些相似性,这将帮助你迁移你的项目:
-
.astro文件的语法类似于 JSX。编写 Astro 应该感觉熟悉。 -
Astro 内置对 Markdown 的支持,并且有一个使用 MDX 文件的集成。此外,你可以配置并继续使用许多现有的 Markdown 插件。
-
Astro 还有一个使用 React 组件的官方集成。注意,在 Astro 中,React 文件必须有
.jsx或.tsx扩展名。 -
Astro 支持安装 NPM 包,包括 React 库。你的许多现有依赖项将在 Astro 中工作。
-
像 Gatsby 一样,Astro 项目可以是 SSG 或者服务端渲染 (SSR) 与页面级预渲染。
Gatsby 和 Astro 之间的关键差异
Section titled “Gatsby 和 Astro 之间的关键差异”当你在 Astro 中重建你的 Gatsby 站点时,你会注意到一些重要的差异:
-
Gatsby 项目是 React 单页应用,并使用
index.js作为你的项目的根。Astro 项目是多页站点,index.astro是你的主页。 -
Astro 组件不是以返回页面模板的出口函数形式编写的。相反,你将你的代码分割为专门为你的 JavaScript 设计的 “代码围栏” 和专门为你生成的 HTML 设计的主体。
-
本地文件数据:Gatsby 使用 GraphQL 从你的项目文件中检索数据。Astro 使用 ESM imports 和顶层 await 函数(例如
import.meta.glob(),getCollection())从你的项目文件中导入数据。你可以手动向你的 Astro 项目添加 GraphQL,但默认情况下不包含它。
转换你的 Gatsby 项目
Section titled “转换你的 Gatsby 项目”每个项目迁移都会有所不同,但是在将 Gatsby 转换为 Astro 时,你将执行一些常见操作。
创建一个新的 Astro 项目
Section titled “创建一个新的 Astro 项目”使用你的包管理器的 create astro 命令启动 Astro 的 CLI 向导,或从 Astro 主题展示中选择一个社区主题。
你可以向 create astro 命令传递一个 --template 参数,以使用我们的官方起始器(例如 docs,blog,portfolio)启动一个新的 Astro 项目。或者,你可以从 GitHub 上的任何现有 Astro 存储库开始一个新项目。
# 启动 Astro CLI 向导npm create astro@latest
# 使用官方示例创建一个新项目npm create astro@latest -- --template <example-name># 启动 Astro CLI 向导pnpm create astro@latest
# 使用官方示例创建一个新项目pnpm create astro@latest --template <example-name># 启动 Astro CLI 向导yarn create astro@latest
# 使用官方示例创建一个新项目yarn create astro@latest --template <example-name>然后,将你现有的 Gatsby 项目文件复制到你的新 Astro 项目中,放在 src 外面的单独文件夹中。
访问 https://astro.new 查看完整的官方起始模板列表,以及在 StackBlitz 或者 CodeSandbox 中打开新项目的链接。
安装集成(可选)
Section titled “安装集成(可选)”在将你的 Gatsby 项目转换为 Astro 时,你可能会发现安装一些Astro 的可选集成很有用:
-
@astrojs/react:在你的新 Astro 站点中重用一些现有的 React UI 组件,或者继续使用 React 组件。
-
@astrojs/mdx:从你的 Gatsby 项目中带来现有的 MDX 文件,或者在你的新 Astro 站点中使用 MDX。
将你的代码放在 src 中
Section titled “将你的代码放在 src 中”按照 Astro 的项目结构:
-
删除 Gatsby 的
public/文件夹。Gatsby 使用
public/目录作为其构建输出,所以你可以安全地丢弃这个文件夹。你将不再需要你的 Gatsby 站点的构建版本。(Astro 默认使用dist/作为构建输出。) -
重命名 Gatsby 的
static/文件夹为public/,并将其用作 Astro 的public/文件夹。Astro 使用一个叫做
public/的文件夹来存放静态资源。你也可以将static/的内容复制到你现有的 Astropublic/文件夹中。 -
复制或移动 Gatsby 的其他文件和文件夹(例如
components,pages等)根据需要将其复制或移动到你的 Astrosrc/文件夹中,重建你的站点,按照 Astro 的项目结构。Astro 的
src/pages/文件夹是一个特殊文件夹,用于基于文件的路由,从.astro、.md和.mdx文件中创建你的站点的页面和文章。你不必为你的 Astro、Markdown 和 MDX 文件配置任何路由行为。所有其他文件夹都是可选的,你可以按照你喜欢的方式组织你的
src/文件夹的内容。Astro 项目中的其他常见文件夹包括src/layouts/、src/components、src/styles和src/scripts。
提示:将 JSX 文件转换为 .astro 文件
Section titled “提示:将 JSX 文件转换为 .astro 文件”以下是将 Gatsby .js 组件转换为 .astro 组件的一些提示:
-
将现有的 Gatsby 组件函数的
return()部分作为你的 HTML 模板。 -
将任何 Gatsby 或 JSX 语法转换为 Astro 语法或 HTML web 标准。例如
<Link to="">,{children}和className。 -
将所有必要的 JavaScript,包括 import 语句,都放入“代码围栏” (
---)中。注意:在 Astro 中,经常会直接在 HTML 模板内编写条件渲染内容的 JavaScript。 -
使用
Astro.props来访问之前传递给你的 Gatsby 函数的任何其他 props。 -
决定是否需要将导入的组件也转换为 Astro。如果已经安装了官方的 React 集成,你可以在 Astro 文件中使用现有的 React 组件。但是,如果他们不需要交互,你可能希望将它们转换为
.astro组件! -
删除任何 GraphQL 查询。改为使用 import 和
import.meta.glob()语句来查询你的本地文件。
对比:.jsx vs .astro
Section titled “对比:.jsx vs .astro”比较以下的 Gatsby 组件与相应的 Astro 组件:
import * as React from "react"import { useStaticQuery, graphql } from "gatsby"import Header from "./header"import Footer from "./footer"import "./layout.css"
const Component = ({ message, children }) => { const data = useStaticQuery(graphql` query SiteTitleQuery { site { siteMetadata { title } } } `) return ( <> <Header siteTitle={data.site.siteMetadata.title} /> <div style={{ margin: `0`, maxWidth: `960`}}>{message}</div> <main>{children}</main> <Footer siteTitle={data.site.siteMetadata} /> </> )}
export default Component---import Header from "./Header.astro"import Footer from "./Footer.astro"import "../styles/stylesheet.css"import { site } from "../data/siteMetaData.js"const { message } = Astro.props---<Header siteTitle={site.title} /> <div style="margin: 0; max-width: 960;">{message}</div> <main> <slot /> </main><Footer siteTitle={site.title} />迁移布局文件
Section titled “迁移布局文件”首先,你可能会发现将你的 Gatsby 布局和模板转换为 Astro 布局组件会很有帮助。
每个 Astro 页面明确要求 <html>、<head> 和 <body> 标签的存在,所以在页面之间复用布局文件是常见的做法。Astro 使用 <slot /> 而不是 React 的 {children} prop 来放置页面内容,并且无需导入语句。你的 Gatsby layout.js 和模板将不会包含这些。
注意标准 HTML 模板以及对 <head> 的直接访问:
<html lang="zh"> <head> <meta charset="utf-8" /> <link rel="icon" type="image/svg+xml" href="/favicon.svg" /> <meta name="viewport" content="width=device-width" /> <title>Astro</title> </head> <body> <!-- 将 slot 元素包裹在你现有的布局模板中 --> <slot /> </body></html>