企业官网建设流程全解析

Gatsby 与 npm：用 Node 包管理器安装、运行与维护 Gatsby 站点的完整指南

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby

npm（Node package manager）是 Node.js 生态的默认包管理器，也是 Gatsby 官方推荐站点开发者使用的依赖管理工具。本文以 docs/docs/glossary/npm.md 为骨架，结合仓库中 gatsby-cli、create-gatsby 等包的源码实现，系统讲解如何在 Gatsby 项目中使用 npm：从全局安装 Gatsby CLI、用 npx 免安装运行，到安装插件与维护依赖锁文件，让你掌握 Gatsby 站点从零搭建到团队协作的完整 npm 工作流。

什么是 npm？

npm，即 Node package manager，是 Node.js JavaScript 运行时自带的默认包管理器。它负责两件核心事情：

• 安装和更新依赖：为基于 Node 的项目安装、升级、卸载各种库与框架（即 dependencies）；
• 与 npm Registry 交互：从全球最大的 JavaScript 包注册表拉取或发布软件包。

在 Gatsby 生态中，你将使用 npm 来安装和升级 Gatsby 本体以及它的各类插件。Gatsby 本身就是通过 npm 发布的开源包，这一点从仓库结构可以直接印证：根目录 package.json 的workspaces字段声明了packages/*这一 monorepo 布局，而gatsby、gatsby-cli等所有核心包都位于 packages 目录下，发布后均可通过npm install <package-name>安装。

npm 是一个命令行工具，你需要使用终端（macOS/Linux 的 Terminal 或 Windows 的 Command Prompt）来执行它的命令。调用方式统一为npm <command>，例如npm help会列出可用功能清单，包括install、uninstall、update和search等常用子命令。

npm 随 Node.js 一起安装

npm 会在 Node.js 的默认安装流程中一并装入你的环境，无需额外步骤。入门教程的环境准备章节建议安装 Node.js v18、v20、v22 或 v24 版本；而当前仓库根 package.json 的engines字段声明了更精确的运行前提：node >=18.0.0 <26、npm >=8.0.0。也就是说，只要你的 Node 版本满足该范围，npm 就已就绪。

安装 Node.js 后，可运行npm --version与node --version验证环境是否正常。

方式一：全局安装 Gatsby CLI（推荐入门）

Gatsby 提供独立的命令行工具包gatsby-cli。从源码看，该包通过bin字段把gatsby命令暴露给终端：packages/gatsby-cli/package.json 中声明了"bin": { "gatsby": "cli.js" }。要直接使用gatsby new这类 CLI 命令，需要将 Gatsby CLI全局安装，使用npm install配合--global（简写-g）标志：

npm install -g gatsby-cli

安装完成后，即可运行gatsby new my-project创建新的 Gatsby 项目。CLI 会接管后续的脚手架搭建、依赖安装与 git 初始化等流程（详见下文"gatsby new背后发生了什么"）。

如果你此前安装过旧版 Gatsby CLI，这条命令会同时将其更新到最新版本。

验证安装：gatsby --version 与 gatsby --help

安装完成后，建议先验证 CLI 是否可用。运行gatsby --version查看版本号——本仓库中gatsby-cli的版本为 5.x（见 packages/gatsby-cli/package.json）；运行gatsby --help则可查看全部可用命令与选项，输出内容如上图所示，涵盖develop、build、serve、info、clean、repl、plugin、new、telemetry、options等命令，以及--verbose、--no-color、--json等全局选项。

方式二：用 npx 免全局安装运行

你同样可以使用npx来安装并运行 Gatsby。npx 随 npm 一同发布，允许你"下载并执行"合二为一：在一条命令里临时拉取目标包并运行其命令，而不污染全局环境。

注意：npx 要求 npm 版本5.2 或更高。如果安装的是最新版 Node 与 npm，通常已自带 npx；否则请先升级 Node 和/或 npm。

例如，与其先执行npm install -g gatsby-cli再执行gatsby new my-project，不如一条命令完成：

npx gatsby new my-project

这条命令会下载并安装最新版 Gatsby，然后在my-project文件夹中创建新的 Gatsby 项目。

不过需要留意两种方式的差异：使用 npx 不会让 Gatsby CLI 全局可用。如果你通过 npx 安装 Gatsby，后续执行 Gatsby 命令时需要一直带上npx前缀，例如npx gatsby develop，或借助项目脚本npm run develop。

利用 starter 内置的 npm run scripts

无论用哪种方式安装，新建的 Gatsby 项目都会在package.json中预置好常用的运行脚本。以仓库内置的 starters/hello-world/package.json 为例：

"scripts": { "build": "gatsby build", "develop": "gatsby develop", "start": "gatsby develop", "serve": "gatsby serve", "clean": "gatsby clean" }

这意味着即使 CLI 未全局安装，你也可以在项目根目录执行npm run develop启动开发服务器、npm run build构建生产版本。这也正是原文档提到的"用npm run执行 Gatsby 命令"的实际落点。

gatsby new 背后发生了什么：源码视角

gatsby new看似简单，内部却是一套完整的脚手架流程。从 packages/gatsby-cli/src/create-cli.ts 的实现看，该命令有两种执行路径：

• 不带任何参数：gatsby new会进入交互式向导（调用create-gatsby包），通过命令行提示帮你选择 CMS、样式方案和插件；
• 带参数：gatsby new <rootPath> <starter>直接调用 initStarter 函数，从指定 starter 克隆或复制模板。

随后initStarter会依次完成：解析并校验项目路径与 starter 地址（目标目录已存在package.json会直接报错，见 init-starter.ts）→ 通过git clone --recursive --depth=1拉取远程 starter（或从本地路径复制）→ 删除 starter 自带的.git目录 → 自动执行依赖安装 → 必要时执行git init并创建初始提交。

其中依赖安装逻辑值得展开，init-starter.ts 的 install 函数 展示了实际执行的 npm 命令：

npm install --loglevel error --color always --legacy-peer-deps --no-audit

• --loglevel error：仅输出错误级别的日志，保持终端干净；
• --legacy-peer-deps：以宽松的 peer 依赖解析方式兼容不同版本的 React 等对等依赖；
• --no-audit：跳过安装时的安全审计，加快安装速度。

同时，CLI 会自动检测包管理器：优先读取配置存储中的cli.packageManager偏好（见 package-manager.ts）；若未设置，则通过环境变量npm_config_user_agent判断你当前使用的是 npm 还是 Yarn。如果最终选择 npm，还会移除 starter 中可能残留的yarn.lock，避免锁文件冲突；反之选择 Yarn 时则删除package-lock.json。

安装完成后，CLI 还会为新项目写入最小化 .gitignore（内容为.cache、node_modules、public三行）并执行首次 git 提交，最后提示你cd my-project && gatsby develop开始开发。

用 npm 安装 Gatsby 插件

Gatsby 拥有数量庞大的插件生态，用于为站点增加功能或接入数据源。安装插件的流程与安装 Gatsby 本身完全相同——把它作为项目依赖装进package.json即可：

npm install gatsby-source-filesystem

以上面这条命令为例，它会将 gatsby-source-filesystem 插件加入项目依赖。关于插件的使用，有两点必须注意：

1. 即使你当初是用 npx 安装的 Gatsby，安装插件依然使用npm install；
2. 仅安装还不够，还需要在gatsby-config.js中注册插件并配置选项，插件的功能才会真正生效。

提交锁文件：保证团队与多设备一致

执行npm install会同时更新项目中的两个文件：package.json（记录依赖的版本范围）和package-lock.json（锁定精确的依赖树与传递依赖版本）。文档特别强调：这两个文件都要提交到项目的代码仓库。

这样做的价值在于：当另一位团队成员git clone你的仓库后，只需运行npm install，npm 就会依据package-lock.json还原出与开发时完全一致的依赖环境，从而让 Gatsby 项目在团队成员与不同电脑之间保持高度一致，避免"我本地能跑，你本地跑不起来"的经典问题。

使用 npm 还是 Yarn？

Gatsby 生态同时支持 npm 与 Yarn 两种包管理器。值得一提的是，Gatsby 官方推荐在站点开发中使用 npm——绝大多数官方教程与示例都以 npm 演示（详见 docs/docs/glossary/yarn.md），这能最大程度避免教程命令与本地环境不一致带来的困惑。Yarn 则主要用于 Gatsby 核心源码开发：当前仓库采用 Yarn workspaces 管理 monorepo，贡献者环境搭建依赖 Yarn 1.x。

如果你更偏好 Yarn，也完全可行。首次运行gatsby new时 CLI 会询问默认包管理器；也可以随时通过gatsby options set pm yarn（或npm）切换偏好，详情见 Gatsby CLI 参考文档。该偏好会写入 CLI 的全局配置文件（~/.config/gatsby/config.json），影响后续所有新项目的依赖安装方式。

小结与延伸阅读

一句话总结 Gatsby 的 npm 工作流：全局装 CLI（npm install -g gatsby-cli）或用 npx 临时运行（npx gatsby new my-project）→ 用npm install <plugin>添加插件并在gatsby-config.js中注册 → 提交package.json与package-lock.json→ 团队成员npm install复现环境。npm 贯穿了 Gatsby 站点的创建、开发、构建与协作全流程。

想继续深入，可以参考仓库内的以下资源：

• Gatsby CLI 完整参考：new、develop、build、serve、info、clean、repl等命令的详细参数与输出示例；
• 环境准备教程：macOS/Linux/Windows 三种平台安装 Node.js 与 Gatsby CLI 的分步指引；
• Node.js 术语表：理解 Gatsby 赖以运行的 JavaScript 运行时；
• Yarn 术语表：了解 npm 之外的备选包管理器及其适用场景。

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby