Gatsby 静态站点生成 SSG

bash npm install -g gatsby-cli

验证安装：

```bash
gatsby --version

创建第一个 Gatsby 项目

使用官方启动器快速搭建项目骨架：

gatsby new my-gatsby-site

该命令会从 gatsby-starter-default 模板克隆代码并安装依赖。完成后进入项目目录：

cd my-gatsby-site

启动开发服务器：

gatsby develop

浏览器访问 http://localhost:8000，你将看到初始页面。修改 src/pages/index.js 文件，页面会实时热更新。

项目结构解析

一个典型的 Gatsby 项目目录结构如下：

my-gatsby-site/
├── src/
│   ├── pages/          # 页面组件，自动生成路由
│   ├── components/     # 可复用 React 组件
│   └── images/         # 图片等静态资源
├── gatsby-config.js    # 站点全局配置与插件声明
├── gatsby-node.js      # Node API，构建流程自定义
├── gatsby-browser.js   # 浏览器端 API
├── gatsby-ssr.js       # 服务端渲染 API
└── package.json

• gatsby-config.js：核心配置文件，添加插件、元数据等。
• gatsby-node.js：在构建阶段动态创建页面（如从 Markdown 生成文章页）。
• src/pages：文件即路由，about.js → /about，index.js → /。

页面与路由

Gatsby 自动将 src/pages 下的组件转换为路由。例如：

// src/pages/about.js
import * as React from 'react'

const AboutPage = () => {
  return (
    <main>
      <h1>关于我们</h1>
      <p>这是一个 Gatsby 示例页面。</p>
    </main>
  )
}

export default AboutPage

访问 http://localhost:8000/about 即可看到该页面。

链接与导航

使用 Gatsby 提供的 Link 组件实现无刷新路由跳转：

import { Link } from 'gatsby'

<Link to="/about">关于</Link>

数据层与 GraphQL 查询

Gatsby 的强大之处在于统一的数据层。插件可以将数据源（文件系统、CMS、API）导入到数据层，你可以在页面组件中通过 GraphQL 查询所需数据。

页面级查询

在页面组件底部导出 pageQuery：

import * as React from 'react'
import { graphql } from 'gatsby'

const HomePage = ({ data }) => {
  return (
    <div>
      <h1>{data.site.siteMetadata.title}</h1>
      <p>{data.site.siteMetadata.description}</p>
    </div>
  )
}

export const query = graphql`
  query HomeQuery {
    site {
      siteMetadata {
        title
        description
      }
    }
  }
`

export default HomePage

data 属性会自动注入组件，包含查询结果。

非页面组件中的静态查询

使用 useStaticQuery 钩子：

import { useStaticQuery, graphql } from 'gatsby'

const Header = () => {
  const data = useStaticQuery(graphql`
    query HeaderQuery {
      site {
        siteMetadata {
          title
        }
      }
    }
  `)
  return <header>{data.site.siteMetadata.title}</header>
}

调试 GraphQL

开发时访问 http://localhost:8000/___graphql 进入 GraphiQL 界面，可在线构建并测试查询。

使用插件扩展能力

插件是 Gatsby 生态的核心，负责引入数据源、图片优化、样式支持等。

安装与配置插件

以读取本地文件系统为例，安装 gatsby-source-filesystem：

npm install gatsby-source-filesystem

编辑 gatsby-config.js：

module.exports = {
  siteMetadata: {
    title: `我的博客`,
    description: `一个 Gatsby 示例站`,
  },
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `blog`,
        path: `${__dirname}/content/blog/`, // 存放 Markdown 文件的目录
      },
    },
  ],
}

重启开发服务器后，文件节点将被注入数据层，你可以在 GraphiQL 中查询 allFile 或 allMarkdownRemark（需搭配 gatsby-transformer-remark）。

常用插件推荐

• gatsby-transformer-remark：解析 Markdown 为可查询的 HTML 和 frontmatter。
• gatsby-plugin-image：提供响应式高性能图片组件。
• gatsby-plugin-sharp：图片处理底层依赖。
• gatsby-plugin-manifest：生成 PWA 清单文件。
• gatsby-plugin-offline：离线支持与服务工作者。

构建与部署

开发完成后，执行构建命令生成生产环境文件：

gatsby build