Gatsby
基于 React 和 GraphQL 数据层、面向内容网站的静态与混合渲染框架。
项目概述
Gatsby 通过 Source Plugin 汇集文件系统、CMS 和 API 数据，再用 React、GraphQL 和逐页渲染策略生成高性能网站，并提供成熟的图片与插件体系。
Gatsby 是采用 MIT 许可证、建立在 React 之上的内容型 Web 框架。它通过 Source Plugin 将文件、Markdown、Headless CMS、数据库与 API 转换成统一的 Node 数据图，并自动生成可由 Page Query、useStaticQuery 和构建 API 使用的 GraphQL Schema。页面默认采用静态生成，也可以逐页选择 Deferred Static Generation 或 Server-Side Rendering；配合 Gatsby Image、文件路由、Head API 和插件生态，适合数据来源多、图片丰富且强调交付性能的内容网站。
主要特点
Gatsby 将 React 页面、统一 GraphQL 数据层、构建插件和图片优化组合成面向内容交付的完整工作流。
React 页面与组件
使用 React 构建布局和交互，页面可通过 src/pages 文件路由创建，也能在 gatsby-node 中根据数据批量生成。
统一 GraphQL 数据层
Source Plugin 将不同数据源转为 Node，Gatsby 自动推断 Schema，让页面以统一查询访问内容、关系和图片。
丰富的 Source Plugin
可接入文件系统、Markdown、WordPress、Contentful、Shopify 等来源，也能通过 Node API 编写自定义数据插件。
多种渲染策略
页面可选择构建时 SSG、首次请求生成的 DSG、每次请求执行的 SSR，或在浏览器中运行的客户端路由。
Gatsby Image
StaticImage 和 GatsbyImage 可生成响应式尺寸、WebP/AVIF、占位图和懒加载，并提前保留比例减少布局偏移。
插件与构建 API
插件可参与数据获取、Schema、页面生成、HTML 与浏览器生命周期，并集成 Sitemap、样式、分析和离线能力。
Head API 与路由能力
页面可导出 Head 设置标题、Meta 和结构化数据，文件路由 API 则支持动态参数和 Collection Route。
缓存与增量构建
构建缓存、内容依赖跟踪和增量构建能减少后续发布工作量，尤其适合 CMS 驱动的持续更新。
适用场景
适合内容来自多个 CMS 或文件源、需要静态优先性能，并希望在少数页面使用 DSG 或 SSR 的 React 网站。
Headless CMS 网站
GraphQL 数据层和 Source Plugin 适合将 CMS 内容、媒体与本地数据统一到 React 页面。
品牌与营销网站
静态优先、图片优化、SEO 和可复用组件适合高流量活动、企业官网和产品介绍。
内容出版平台
Markdown/CMS、页面模板、分类分页和 Feed 插件可支撑博客、杂志与多作者内容。
电商内容前台
商品数据、CMS 营销内容和图片可在构建期整合，库存与购物车则通过客户端 API 或 SSR 更新。
大型文档与知识站
程序化页面、MDX、搜索索引和版本化数据源适合组件文档、帮助中心与知识库。
多数据源门户
不同 API、文件与 SaaS 数据可转换为统一 Schema，减少页面组件对各后端格式的直接依赖。
优点与注意事项
技术选型不仅要看能力，也要理解它带来的团队成本。
主要优点
Gatsby 擅长的地方
- React 组件模型成熟，交互界面和内容模板可以统一开发
- GraphQL 数据层能规范多个 CMS、文件和 API 的访问方式
- Source Plugin 与网站功能插件生态覆盖大量常见集成
- Gatsby Image 提供完整的构建期响应式图片优化
- SSG、DSG 与 SSR 可按页面选择，兼顾构建成本和内容新鲜度
- 静态页面可部署到 CDN，并保持良好的首屏与 SEO 基础
需要注意
采用前应考虑的问题
简单数据也会经过 Node 和 Schema；大型项目应定义类型并使用 GraphiQL 检查查询，避免自动推断随内容变化。
大量页面、远程内容和图片会增加内存与构建时间，应保留缓存、限制图片变体并评估 DSG 或分站策略。
第三方插件可能滞后于 Gatsby、React 或 Node.js 版本，升级前应检查维护状态、Peer Dependency 和构建日志。
静态 HTML 通常会由 React Hydration 接管，组件和依赖过多会扩大 Bundle；纯内容区域应减少客户端逻辑。
纯 SSG 可部署到任意静态平台，但 DSG、SSR、重写和函数要求托管适配器或兼容运行环境。
构建期数据不会自动实时更新，应为 CMS Webhook、预览、缓存失效和发布失败建立明确流程。
快速开始
用官方初始化器创建 TypeScript 项目，接入本地 Markdown，查询 GraphQL 数据并生成首页与生产文件。
bashnpm init gatsby my-gatsby-site -- -ts
cd my-gatsby-site
npm run develop
# 本地网站：http://localhost:8000
# GraphiQL：http://localhost:8000/___graphqlbashnpm install gatsby-source-filesystem gatsby-transformer-remarktypescript// gatsby-config.ts
import type { GatsbyConfig } from "gatsby";
const config: GatsbyConfig = {
siteMetadata: {
title: "开源项目志",
siteUrl: "https://example.org",
},
plugins: [
{
resolve: "gatsby-source-filesystem",
options: {
name: "posts",
path: "./content/posts",
},
},
"gatsby-transformer-remark",
],
};
export default config;markdown---
title: "Hello Gatsby"
date: "2026-07-24"
description: "使用 React 和 GraphQL 构建内容网站"
---
Gatsby 会把 Markdown 转换为 GraphQL Node，
页面可以在构建时查询并渲染这些内容。tsx// src/pages/index.tsx
import * as React from "react";
import { graphql, type HeadFC, type PageProps } from "gatsby";
type Data = {
allMarkdownRemark: {
nodes: Array<{
id: string;
frontmatter: {
title: string;
date: string;
description: string;
};
}>;
};
};
export default function IndexPage({ data }: PageProps<Data>) {
return (
<main>
<h1>开源项目志</h1>
{data.allMarkdownRemark.nodes.map(({ id, frontmatter }) => (
<article key={id}>
<h2>{frontmatter.title}</h2>
<p>{frontmatter.description}</p>
<time>{frontmatter.date}</time>
</article>
))}
</main>
);
}
export const query = graphql`
query HomePage {
allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
nodes {
id
frontmatter {
title
date(formatString: "YYYY-MM-DD")
description
}
}
}
}
`;
export const Head: HeadFC = () => <title>开源项目志</title>;bashnpm run build
npm run serve
# 静态构建结果位于 public 目录下一步：对长期维护的项目，应显式定义关键 GraphQL 类型，固定 Gatsby 与插件版本，并在 CI 中保留 .cache；上线前还要确认托管平台是否完整支持所使用的 DSG、SSR 和函数能力。
类似项目
这些框架同样支持 React 或内容驱动网站，但在数据层、运行时模型和服务端能力上采用不同取舍。
Docusaurus
由 Meta 维护，使用 React、MDX 和插件系统构建文档及内容网站的静态站点生成器。
查看项目Next.js
基于 React 的全栈 Web 框架，覆盖渲染、路由和部署。
查看项目Astro
面向内容网站的 Web 框架，默认发送更少的客户端 JavaScript。
查看项目Eleventy
灵活、稳定且支持多种模板语言的 JavaScript 静态站点生成器。
查看项目React
用于构建 Web 和原生用户界面的组件化 JavaScript 库。
查看项目Gridsome
基于 Vue 和 GraphQL 数据层构建静态网站的 Jamstack 框架。
访问官网Gatsby vs Next.js
Gatsby 与 Next.js 都使用 React 并支持静态和服务端渲染；Gatsby 以 Source Plugin、统一 GraphQL 数据层和内容构建管线见长，Next.js 则以 React Server Components、全栈路由和请求时数据访问见长。
| 比较维度 | Gatsby | Next.js |
|---|---|---|
| 核心定位 | 内容型 React 框架与统一数据构建层 | 通用 React 全栈 Web 框架 |
| 数据访问 | Source Plugin 汇入 Node，通过 GraphQL 查询 | 组件靠近数据源直接使用 fetch、数据库或 SDK |
| 默认渲染 | SSG，页面可选择 DSG 或 SSR | Server Components，可静态、动态或流式渲染 |
| 路由 | src/pages、文件路由 API 和 createPages | App Router、嵌套 Layout、Route Handler 和动态段 |
| 图片 | Gatsby Image、GraphQL Resolver 与 Sharp | next/image 在请求或构建流程中优化图片 |
| 扩展生态 | Source、Transformer 与功能插件 | React/npm 生态与托管平台集成 |
| 服务端能力 | SSR 页面和函数可用，但不是主要内容模型 | Server Actions、Route Handlers 和中间件更完整 |
| 更适合 | 多 CMS、图片丰富、静态优先的内容网站 | SaaS、电商、认证和服务端业务逻辑较多的应用 |
如果网站主要是内容交付，需要把多个 CMS 与本地文件统一成可查询 Schema，并重视构建期图片优化，Gatsby 仍有鲜明优势；如果应用包含大量请求时数据、认证、数据变更和后端路由，Next.js 的全栈模型通常更直接。采用 Gatsby 前应以真实数据量测试冷构建、插件兼容性和目标平台的 DSG/SSR 支持。
资料核验
版本、维护信息与本页采用的官方资料来源。
本次核验覆盖 Gatsby 的核心定位、主要能力、官方入口与开源许可。项目版本持续更新，具体补丁版本、兼容性和迁移要求请在采用前继续核对官方发布记录。
官方仓库未归档，核验时最近可见的代码活动日期为 2026 年 7 月 25 日。该状态表示项目近期仍有公开维护活动，不代表固定发布频率或长期支持承诺。