使用 Gatsby 本地插件（Local Plugins）：在多种加载方式下组织站点插件

使用 Gatsby 本地插件（Local Plugins）：在多种加载方式下组织站点插件

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

导读

本篇文章基于 Gatsby 仓库中的using-multiple-local-plugins示例，系统讲解在 Gatsby 站点中加载**本地插件（Local Plugins）**的多种方式。你将学到：如何把插件放进站点自带的plugins目录、如何用require.resolve引用站点外部项目中的插件、如何借助npm link/yarn link以依赖方式加载插件，以及这些插件如何通过onPreInit等 Gatsby Node API 按顺序参与站点的开发与构建流程。读完本文，你将能够根据实际项目结构，为你的 Gatsby 站点灵活组织本地插件并正确调试其加载顺序。

示例项目概览

本示例位于仓库的 examples/using-multiple-local-plugins 目录，其核心目标是演示在同一个 Gatsby 站点中，以多种不同的方式加载本地插件。真正的 Gatsby 站点位于该目录下的gatsby-site-using-local-plugins子目录中，站点结构如下：

examples/using-multiple-local-plugins/ ├── gatsby-plugin-console-log-b/ # 站点外部项目：通过 require.resolve 引入 ├── gatsby-plugin-console-log-c/ # 站点外部项目：通过 npm/yarn link 引入 └── gatsby-site-using-local-plugins/ # 实际可运行的 Gatsby 站点 ├── plugins/ │ └── gatsby-plugin-console-log-a/ # 站点自带 plugins 目录中的插件 ├── src/ │ ├── components/ # header、layout 等页面组件 │ └── pages/ # 404.js、index.js 页面 ├── gatsby-config.js # 站点插件配置入口 ├── gatsby-node.js # 站点自身的 Node API 实现 └── package.json

为了验证插件的加载情况，示例实现了一个功能极其简单的gatsby-plugin-console-log插件：它只挂钩onPreInit这个 Gatsby Node API，在站点启动（develop 或 build 模式）时向控制台打印一行日志。同一个插件被实现了 3 次（外加站点自身gatsby-node.js中的 1 次），以便对比观察 4 种加载方式下的执行顺序与效果。

第一步：运行示例站点

进入站点目录并安装依赖：

cd examples/using-multiple-local-plugins/gatsby-site-using-local-plugins npm install

然后启动开发服务器：

gatsby develop

在命令行输出中，你应该能看到如下文本。这段输出展示了各个插件借助其实现的 Node API 被顺序执行的过程：

$ gatsby develop success open and validate gatsby-configs - 0.051s success load plugins - 1.047s logging to the console from plugins folder logging to the console from a plugin in another project with require.resolve logging to the console from site's gatsby-node success onPreInit - 0.023s

注意：上面的输出对应的是默认配置下（gatsby-plugin-console-log-c尚未启用）的结果。站点自身gatsby-node.js中的onPreInit实现也会打印一行日志，因此默认情况下会看到 3 条日志输出。

第二步：4 种本地插件加载方式

该示例的核心价值在于演示了 4 种让插件代码参与站点运行的方式：

1. 写在站点自身的gatsby-node.js中（见 gatsby-site-using-local-plugins/gatsby-node.js）；
2. 放在站点plugins目录中，即插件gatsby-plugin-console-log-a（见 plugins/gatsby-plugin-console-log-a/gatsby-node.js）；
3. 放在站点外部的独立项目中，通过require.resolve在配置里显式引入，即插件gatsby-plugin-console-log-b（见 gatsby-plugin-console-log-b/gatsby-node.js）；
4. 放在站点外部的独立项目中，通过npm link/yarn link以符号链接方式引入，即插件gatsby-plugin-console-log-c（见 gatsby-plugin-console-log-c/gatsby-node.js）。

四个实现体的代码几乎完全一致，均类似如下写法，只是打印的日志文本不同：

exports.onPreInit = () => { console.log("logging to the console...") }

从源码结构看，这 4 种方式最终都会在 Gatsby 加载插件阶段被收集，并依次触发其onPreInit钩子，因此非常适合用来直观地理解本地插件的解析与执行顺序。

第三步：gatsby-config.js 中的三种引用方式

站点插件配置的核心位于 gatsby-site-using-local-plugins/gatsby-config.js。下面逐段解析其中的三种引用方式：

module.exports = { siteMetadata: { title: `Using Multiple Local Plugins`, description: `An example Gatsby site utilizing multiple local plugins`, author: `@gatsbyjs`, }, plugins: [ `gatsby-plugin-react-helmet`, // including a plugin from the plugins folder `gatsby-plugin-console-log-a`, { // including a plugin from outside the plugins folder needs the path to it resolve: require.resolve(`../gatsby-plugin-console-log-b`), }, // including a plugin with yarn or npm link // in order for this plugin to be found when you run gatsby develop // you first need to run `npm link ../gatsby-plugin-console-log-c` in the `gatsby-site-using-local-plugins` root folder `gatsby-plugin-console-log-c`, // highlight-line ], }

方式一：字符串引用 +plugins目录自动解析

`gatsby-plugin-console-log-a`,

当配置项以字符串形式给出插件名时，Gatsby 会按 Node.js 模块解析规则查找该插件。站点根目录下的plugins文件夹是 Gatsby 预留的本地插件目录，插件gatsby-plugin-console-log-a被放在这里后，无需任何额外路径信息即可被自动解析加载。这是最"开箱即用"的本地插件方式：只要插件目录存在于站点根目录的plugins/下，gatsby-config.js里用插件名引用即可。

方式二：对象 +require.resolve显式指定路径

{ // including a plugin from outside the plugins folder needs the path to it resolve: require.resolve(`../gatsby-plugin-console-log-b`), },

当插件位于站点plugins目录之外时，仅靠字符串引用无法被找到。此时需要使用对象形式的配置，通过resolve字段提供插件入口文件的绝对路径。示例中使用了 Node.js 内置的require.resolve()将相对路径../gatsby-plugin-console-log-b解析为绝对路径：gatsby-plugin-console-log-b与站点目录gatsby-site-using-local-plugins是同级的兄弟目录，因此../恰好指向其所在位置。这种方式非常适合站点与插件处于同一仓库、但插件并不在plugins目录内的 monorepo 或多项目场景。

方式三：字符串引用 +npm link/yarn link

`gatsby-plugin-console-log-c`,

插件gatsby-plugin-console-log-c同样位于站点外部，但在配置中仍以普通字符串引用。其可行性依赖一个前提：必须在站点目录下执行过链接命令，将该插件符号链接进站点自己的node_modules，使 Node 的模块解析能够"看见"它。具体命令为：

npm link ../gatsby-plugin-console-log-c

（使用 Yarn 时对应执行yarn link ../gatsby-plugin-console-log-c。）

执行链接后再运行gatsby develop，控制台会多出一行日志，与之前输出对比即可看到第四种方式生效：

$ gatsby develop success open and validate gatsby-configs - 0.051s success load plugins - 1.047s logging to the console from plugins folder logging to the console from a plugin in another project with require.resolve + logging to the console from a plugin in another project with npm/yarn link logging to the console from site's gatsby-node success onPreInit - 0.023s

源码佐证：三个插件的真实结构

三个console-log插件的package.json结构完全一致，其关键字段如下（以gatsby-plugin-console-log-b为例，见 gatsby-plugin-console-log-b/package.json）：

{ "name": "gatsby-plugin-console-log-b", "version": "1.0.0", "description": "Log stuff in a Gatsby site's build process", "main": "index.js", "license": "MIT" }

值得说明的是：三个插件的index.js都只是一个// noop空实现（例如 gatsby-plugin-console-log-b/index.js），真正的逻辑全部放在gatsby-node.js的onPreInit钩子中。这印证了 Gatsby 插件机制的核心事实：Gatsby 运行时并不要求插件导出浏览器端逻辑，只要实现对应的 Node API（如onPreInit、createPages、onCreateWebpackConfig等），插件就能参与构建流程。这里的main字段指向index.js，是插件作为 npm 包被 Node 模块系统解析时的入口，而 Gatsby 会额外读取插件内的gatsby-node.js来挂载 Node API。

执行顺序与输出解读

在上述 4 种方式同时启用时，gatsby develop的日志输出顺序为：

1. success open and validate gatsby-configs—— Gatsby 首先读取并校验gatsby-config.js；
2. success load plugins—— Gatsby 按配置顺序加载所有插件（含本地插件与gatsby-plugin-react-helmet等 npm 依赖插件）；
3. 来自plugins目录插件的日志（gatsby-plugin-console-log-a）；
4. 来自require.resolve引入插件的日志（gatsby-plugin-console-log-b）；
5. 来自npm/yarn link引入插件的日志（gatsby-plugin-console-log-c）；
6. 来自站点自身gatsby-node.js的日志；
7. success onPreInit—— 所有插件的onPreInit钩子执行完毕。

从该输出可以直观推断两点：其一，onPreInit是 Gatsby 启动流程中较早的生命周期钩子，发生在站点数据获取、页面创建等阶段之前，适合做全局初始化或日志埋点；其二，插件钩子与站点自身gatsby-node.js中的同名钩子会被按加载顺序依次触发，最终共同构成完整的启动时序。无论运行gatsby develop还是gatsby build，这套加载与执行流程都一致。

本地插件的适用场景小结

综合示例代码可以总结出三种加载方式各自的适用场景：

需要特别强调的是第三种方式的运行时前提：若未执行npm link ../gatsby-plugin-console-log-c，则gatsby develop会因无法解析gatsby-plugin-console-log-c模块而报错，这正是示例 README 中要求"先链接、后运行"的原因。

进阶参考

• 若希望了解更复杂的本地插件示例（例如带选项配置、gatsby-browser.js/gatsby-ssr.js、资源处理等能力的完整插件），可参考仓库中的 examples/using-local-plugins 示例。
• 插件在构建期如何挂载 Node API 的底层机制，可进一步阅读 packages/gatsby 中关于插件加载与生命周期执行的源码。
• 关于本地插件加载方式的更多文档化说明，可参阅仓库中与插件加载相关的文档章节（如 docs/docs/creating-plugins.md）。

通过本示例，你应该已经掌握了在 Gatsby 站点中灵活组织本地插件的三种核心路径，以及如何借助onPreInit日志快速验证插件的加载顺序。这套机制同样适用于createPages、onCreateWebpackConfig等其他 Node API——把本地插件的加载方式与生命周期钩子组合使用，即可构建出高度模块化、便于本地开发调试的 Gatsby 站点。

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