Gatsby是一款基于React和GraphQL的现代化静态站点生成器，以MIT协议开源。Gatsby诞生于2015年，以极致的性能、现代化的开发体验、丰富的插件生态著称。Gatsby采用React组件化开发，使用GraphQL查询数据，支持从Markdown、WordPress、Contentful等多种数据源拉取内容，生成优化的静态HTML网站。Gatsby适合搭建个人博客、企业官网、电商网站、文档站点、作品集。
核心优势：基于React（组件化开发）、GraphQL数据层、极致性能（自动优化图片、代码分割、预加载）、丰富的插件和主题生态、支持多种数据源、PWA支持、完全静态（无需数据库）、部署灵活、开发者体验极佳。Gatsby是React开发者和追求性能的用户首选的静态站点生成器。
环境要求
- 操作系统：Windows / macOS / Linux
- Node.js版本：Node.js 18.x 或 20.x（Gatsby 5.x推荐Node 18/20 LTS）
- npm版本：npm 9.x+ 或 yarn 1.22+
- Git：用于版本管理和部署（推荐）
- 内存：最低2GB，推荐4GB以上（构建过程需要较多内存）
- 磁盘：至少2GB可用空间
- Web服务器：Nginx（静态托管，可选）
- 开发工具：VS Code（推荐，内置React和GraphQL支持）
安装教程
步骤1：安装Node.js和Git
Windows：
- 从Node.js官网（https://nodejs.org）下载LTS版本安装
- 从Git官网（https://git-scm.com）下载安装Git
- 打开命令提示符验证：
node --version、npm --version、git --version
Linux（Ubuntu/Debian）：
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs git
node --version
npm --version
git --version步骤2：安装Gatsby CLI
npm install -g gatsby-cli
gatsby --version步骤3：创建Gatsby站点
gatsby new my-gatsby-site https://github.com/gatsbyjs/gatsby-starter-default
cd my-gatsby-site这会使用默认模板创建一个Gatsby站点，包含示例页面和组件。
常用模板推荐：
- gatsby-starter-default：默认模板，适合学习
- gatsby-starter-blog：博客模板，支持Markdown
- gatsby-starter-portfolio：作品集模板
- gatsby-starter-business：企业官网模板
步骤4：本地开发预览
gatsby developGatsby开发服务器默认运行在8000端口，访问 http://localhost:8000 即可看到网站。GraphQL调试工具在 http://localhost:8000/___graphql。
步骤5：配置站点信息
编辑 gatsby-config.js 文件：
module.exports = {
siteMetadata: {
title: `我的博客`,
description: `分享技术与生活`,
author: `@yourname`,
siteUrl: `https://yourdomain.com`,
},
plugins: [
`gatsby-plugin-react-helmet`,
`gatsby-plugin-image`,
`gatsby-plugin-sharp`,
`gatsby-transformer-sharp`,
{
resolve: `gatsby-source-filesystem`,
options: {
name: `images`,
path: `${__dirname}/src/images`,
},
},
{
resolve: `gatsby-plugin-manifest`,
options: {
name: `我的博客`,
short_name: `blog`,
start_url: `/`,
background_color: `#663399`,
theme_color: `#663399`,
display: `minimal-ui`,
icon: `src/images/gatsby-icon.png`,
},
},
`gatsby-plugin-offline`,
],
}步骤6：创建页面和文章
Gatsby使用React组件创建页面，在 src/pages 目录下创建JS文件即为页面：
// src/pages/about.js
import * as React from 'react'
const AboutPage = () => {
return (
关于我
这是关于页面的内容。
)
}
export default AboutPage博客文章使用Markdown，在 content/blog 目录下创建文件夹和index.md：
---
title: "我的第一篇文章"
date: "2026-09-12"
description: "文章描述"
---
这里是文章正文，使用Markdown语法。
## 二级标题
正文内容...步骤7：构建生产版本
gatsby build生成的静态文件保存在 public 目录下。Gatsby会自动优化图片、压缩代码、生成预加载链接。
步骤8：部署到Netlify或Vercel（推荐）
Netlify部署：
- 将代码推送到GitHub仓库
- 登录Netlify（https://www.netlify.com），点击”New site from Git”
- 选择GitHub仓库，配置构建命令（gatsby build）和发布目录（public）
- 点击”Deploy site”，Netlify自动构建部署
Vercel部署：
- 将代码推送到GitHub仓库
- 登录Vercel（https://vercel.com），点击”New Project”
- 导入GitHub仓库，Vercel自动识别Gatsby项目
- 点击”Deploy”，自动构建部署
步骤9：部署到GitHub Pages
npm install gh-pages --save-dev在package.json中添加：
{
"scripts": {
"deploy": "gatsby build && gh-pages -d public -b main"
}
}执行部署：npm run deploy
步骤10：部署到自有服务器
将 public 目录下的所有文件上传到服务器网站根目录即可，无需Node.js、数据库等环境。
# 使用rsync同步到服务器
rsync -avz --delete public/ user@yourserver:/www/wwwroot/yourdomain.com/Windows环境注意事项
- 确保安装了Node.js LTS版本（18.x/20.x）
- 建议使用Git Bash或Windows Terminal
- 构建过程需要较多内存，确保至少4GB可用内存
- 如果构建失败，尝试设置环境变量：
set NODE_OPTIONS=--max-old-space-size=4096
宝塔面板部署（静态站点）
- 在本地执行
gatsby build生成静态文件 - 宝塔面板添加站点，PHP版本选择”纯静态”
- 将
public目录下的所有文件上传到网站根目录 - 配置Nginx：开启gzip压缩，设置静态资源缓存（Gatsby生成的文件带hash，可长缓存）
- 配置SSL证书（宝塔一键部署Let’s Encrypt）
- 可选：配置Webhook实现自动部署
服务器配置建议（自有服务器部署）
- Nginx配置纯静态站点，无需Node.js/PHP/MySQL
- 启用gzip/brotli压缩
- Gatsby生成的静态资源（JS/CSS/图片）带内容hash，可设置长期缓存（1年）
- HTML文件设置短缓存或不缓存
- 配置HTTPS（Let’s Encrypt免费证书）
- 设置404页面（Gatsby默认生成404.html）
- 使用CDN加速静态资源
- 构建时使用生产环境：
gatsby build（默认就是生产模式）
常见问题
Q：gatsby build失败，提示内存溢出？
A：增加Node.js内存限制：NODE_OPTIONS=--max-old-space-size=4096 gatsby build。确保服务器内存至少4GB，必要时创建swap分区。
Q：gatsby develop启动后无法访问？
A：检查8000端口是否被占用，可指定其他端口：gatsby develop -p 5000。检查防火墙是否开放端口。
Q：图片不显示或加载慢？
A：确保安装了gatsby-plugin-image和gatsby-plugin-sharp插件，使用GatsbyImage组件优化图片。Gatsby会自动生成多种尺寸和格式（WebP/AVIF）。
Q：Gatsby和Next.js怎么选？
A：纯静态站点、博客、营销页选Gatsby；需要SSR/ISR、动态功能、全栈应用选Next.js。Gatsby更专注静态优化，Next.js更灵活全面。
Q：Gatsby和Hexo怎么选？
A：追求React组件化、GraphQL、极致性能选Gatsby；追求简单快速、Markdown博客、轻量选Hexo。技术博客和复杂站点推荐Gatsby，普通个人博客推荐Hexo。
官方网址
Gatsby官网地址：https://www.gatsbyjs.com