在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

gatsbyjs/gatsby

菜单

CLI 与命令

相关源文件

Gatsby CLI（命令行界面）是一个关键工具，使开发人员能够执行 Gatsby 网站的必要操作，包括初始化、开发、构建和部署。本文档涵盖了可用的 CLI 命令、它们的选项以及它们如何与 Gatsby 的核心系统进行交互。

有关开发环境设置的详细信息，请参阅 开发体验 和 测试和 CI/CD。

CLI 概述

Gatsby 通过两个包提供命令行界面

  1. gatsby-cli - 一个可以全局安装的独立包
  2. gatsby - 核心包，在项目本地安装时包含 CLI 功能

CLI 是开发人员与 Gatsby 生态系统之间的主要接口，允许执行创建新站点、启动开发服务器、构建生产就绪的网站等操作。

来源

安装选项

您可以通过多种方式使用 Gatsby CLI

  1. 全局安装：使用 npm 或 yarn 全局安装 gatsby-cli

  2. 本地项目使用：使用项目中 gatsby 包自带的 CLI

  3. 直接 NPX 使用：使用 npx 运行 gatsby 命令而无需安装

  4. 运行脚本：使用 package.json 中预定义的脚本（在 starter 中很常见）

来源

核心命令

Gatsby CLI 提供了几个核心命令来管理 Gatsby 项目的整个生命周期

new

通过交互式提示或克隆 starter 来创建一个新的 Gatsby 站点。

该命令运行一个交互式 shell，帮助您使用 CMS 集成、样式系统和插件来配置新站点。

开发

为本地开发启动带有热重载的开发服务器。

主要选项包括

  • -H, --host：设置主机（默认为 localhost）
  • -p, --port：设置端口（默认为 8000）
  • -o, --open：在浏览器中打开
  • -S, --https：使用 HTTPS
  • --inspect：打开调试端口
  • --verbose：显示详细输出

来源

build

编译您网站的生产就绪版本。

主要选项包括

  • --prefix-paths：使用前缀路径构建
  • --no-uglify：构建时不混淆 JS 捆绑包
  • --profile：构建时进行 React 分析
  • --open-tracing-config-file：OpenTracing 配置
  • --graphql-tracing：跟踪 GraphQL 解析器
  • --no-color：禁用彩色输出

来源

serve

为测试提供生产构建的站点。

主要选项包括

  • -H, --host：设置主机（默认为 localhost）
  • -p, --port：设置端口（默认为 9000）
  • -o, --open：在浏览器中打开
  • --prefix-paths：使用前缀路径提供服务

来源

info

提供有关本地环境和 Gatsby 安装的信息。

选项

  • -C, --clipboard：将信息复制到剪贴板

来源

clean

清除缓存（.cache）和 public 目录。

这有助于解决开发过程中可能出现的各种缓存问题。

来源

repl

打开一个 Node.js REPL（读取-求值-打印-循环），其中包含您的 Gatsby 环境的上下文。

这提供了一个交互式 shell 来探索 Gatsby 的内部数据结构。

来源

命令执行过程

当您运行 Gatsby CLI 命令时，会发生以下过程

来源

环境变量和配置

Gatsby CLI 的行为可以通过环境变量和配置设置进行修改。

环境变量

  • GATSBY_CONCURRENT_DOWNLOAD：设置并发下载数量
  • GATSBY_CPU_COUNT：控制工作进程的数量
  • GATSBY_EXPERIMENTAL_LMDB_STORE：使用 LMDB 进行节点存储
  • GATSBY_LOG_LEVEL：设置日志详细程度
  • GATSBY_SKIP_FORCE_POSTINSTALL：跳过特定的安装后进程
  • GATSBY_TELEMETRY_DISABLED：禁用遥测收集
  • REACT_PROFILE：启用 React 分析（替代 --profile 标志）

来源

CLI 配置

Gatsby CLI 将配置存储在 ~/.config/gatsby/config.json 中。您可以修改此文件来更改默认行为。

最常见的配置是设置您偏好的包管理器

您也可以使用 options 命令来设置此项

来源

CLI 架构

Gatsby CLI 与核心 Gatsby 系统集成，并与各种组件交互

来源

适配器集成

从 Gatsby 5.12.0 开始，CLI 集成了用于部署的适配器系统

来源

故障排除和高级用法

常见问题

  1. 陈旧数据或 GraphQL 错误：使用 gatsby clean 来清除缓存
  2. 依赖项问题：检查 package.json 中的版本冲突
  3. 端口冲突：使用 -p 标志来指定不同的端口
  4. 内存问题：使用 NODE_OPTIONS=--max_old_space_size=4096 设置 Node.js 内存限制

使用 Gatsby CLI 进行 Gatsby 开发

在开发 Gatsby CLI 本身时，过程会更复杂

  1. 克隆 Gatsby monorepo
  2. 使用 yarn bootstrap 进行设置
  3. 使用 gatsby-dev-cli 将更改复制到测试站点

来源

与其他工具的集成

gatsby-codemods

gatsby-codemods 包提供了 codemod 脚本，用于在 Gatsby 版本之间升级您的代码库

来源

React 性能分析

--profile 标志会启用对您的 Gatsby 应用程序的 React 性能分析

您也可以设置 REACT_PROFILE 环境变量来启用此功能。

来源

结论

Gatsby CLI 是一个强大的工具，构成了开发者与 Gatsby 框架之间核心接口。理解其命令和选项对于高效的 Gatsby 开发至关重要。CLI 与 Gatsby 的核心流程深度集成，从开发、构建到通过适配器系统的部署。