gatsby-core-utils 源码解析Gatsby 全栈共用的核心工具库与版本演进【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsbygatsby-core-utils是 Gatsby 仓库中几乎所有包gatsby主包、CLI、插件、Transformer、Source 插件等都会依赖的底层工具库职责是Utilities used in multiple Gatsby packages见 packages/gatsby-core-utils/README.md。本文以该包自身的 CHANGELOG.md 为主线结合 源码目录 与测试用例系统梳理其核心 API 的实现原理、配置参数与版本演进脉络。读完本文你将掌握内容摘要、CPU 核数探测、CI 环境识别、跨进程互斥锁、远程文件下载与哈希计算等工具的正确用法并能理解这些能力如何在 Gatsby 构建管线中发挥作用。一、包定位一个 index.ts 导出的工具箱gatsby-core-utils不是单一功能的包而是一个聚合导出层。其全部公开能力集中在 src/index.tsexport { createContentDigest } from ./create-content-digest export { isNodeInternalModulePath, joinPath, slash } from ./path export { cpuCoreCount } from ./cpu-core-count export { urlResolve } from ./url export { getCIName, isCI } from ./ci export { createRequireFromPath } from ./create-require-from-path export { getConfigStore } from ./get-config-store export { getGatsbyVersion } from ./get-gatsby-version export { getTermProgram } from ./get-term-program export { fetchRemoteFile } from ./fetch-remote-file export { isTruthy } from ./is-truthy export * as uuid from ./uuid export { getMatchPath } from ./match-path export * from ./service-lock export * from ./site-metadata export * from ./page-data export * from ./page-html export * from ./parse-component-path export { listPlugins } from ./list-plugins export { createFilePath } from ./filename-utils export { readConfigFile, getConfigPath } from ./utils export { lock } from ./lock export { murmurhash } from ./murmurhash export * from ./hash export { md5File } from ./md5-file安装方式见 READMEnpm install gatsby-core-utilsconst { createContentDigest, cpuCoreCount, joinPath, isCI, getCIName } require(gatsby-core-utils)从 CHANGELOG 的早期记录可以看到该包的诞生与成长1.0.0 版本2019-07-08首次创建1.0.17 加入isCI/getCIName1.0.22 让createContentDigest变得确定性deterministic2.0.0 加入文件下载函数并把isTruthy迁入4.0.0 把murmurhash迁入——每次版本演进都对应着某一项能力被抽出来供全仓库复用。二、createContentDigest确定性的内容摘要createContentDigest是 Gatsby 插件生态中使用频率最高的函数之一Source/Transformer 插件常用来为节点生成唯一 id 或内容 hash。README 给出的用法const { createContentDigest } require(gatsby-core-utils) const options { key: value, foo: bar } const digest createContentDigest(options)实现细节见 src/create-content-digest.tsconst hasher objectHash({ coerce: false, alg: md5, enc: hex, sort: { map: true, object: true, array: false, set: false }, }) const hashPrimitive (input) crypto.createHash(md5).update(input).digest(hex) export const createContentDigest (input) { if (typeof input object !Buffer.isBuffer(input)) { return hasher.hash(input) } return hashPrimitive(input) }三个关键点值得注意对象入参与原始入参走两条路径对象交给node-object-hash序列化后哈希字符串/Buffer 等原始类型直接用 Node 内置crypto的 MD5 hex 摘要。确定性由排序保证sort配置对map和object开启排序因此相同键值内容的对象无论属性书写顺序如何都会得到相同 digest这正对应 CHANGELOG 1.0.22 中make createContentDigest deterministic的修复。coerce: false不进行类型强转避免 1 与 1 产生相同哈希而引发缓存污染。配套测试见 src/tests/create-content-digest.ts。三、cpuCoreCount用 GATSBY_CPU_COUNT 控制并发规模Gatsby 构建是多核并行的cpuCoreCount用于确定并行 worker 数量。README 中给出的环境变量控制表值说明空/未设置通过 shell 命令统计真实物理核心数logical_cores用require(os).cpus()统计全部虚拟/逻辑核心数任意数字将 CPU 数固定为该数字用法const { cpuCoreCount } require(gatsby-core-utils) const coreCount cpuCoreCount(false) // 忽略环境变量返回物理核数process.env.GATSBY_CPU_COUNT logical_cores const coreCount cpuCoreCount() // 返回逻辑核数源码实现src/cpu-core-count.ts的优先级逻辑先调用getPhysicalCpuCount()见 src/physical-cpu-count.ts通过 shell 命令统计得到物理核数探测失败时回退为 1若ignoreEnvVar为true直接返回物理核数否则读取process.env.GATSBY_CPU_COUNT为字符串logical_cores时用os.cpus().length统计逻辑核数且统计失败会抛出明确错误信息为数字时直接采用该值其余情况保持默认。该 API 的调用方遍布构建管线如并行 page 生成、静态资源处理因此在 CI 环境里用GATSBY_CPU_COUNT显式限流是控制构建资源占用的常用手段。CHANGELOG 4.0.0 中还记录了Update README with correct cpuCoreCount args说明该函数签名ignoreEnvVar参数有过文档修正的细节。四、路径与 URL 工具joinPath、slash、urlResolve 与 createFilePath跨平台路径处理是构建工具的老大难。gatsby-core-utils提供了一组路径工具src/path.tsconst { joinPath } require(gatsby-core-utils) const BASEPATH /mybase/ const pathname ./gatsby/is/awesome const url joinPath(BASEPATH, pathname)joinPath在 Windows 与 Unix 上统一用/拼接路径README 明确说明它can also be used for URL concatenation也可用于 URL 拼接slash把 Windows 反斜杠路径转换为正斜杠供 URL 使用isNodeInternalModulePath判断路径是否为 Node 内部模块路径urlResolveURL 解析src/url.tscreateFilePathsrc/filename-utils.ts把目录、文件名、扩展名组合成安全路径。这些工具在 CHANGELOG 中频繁出现的两个主题相关3.12.0 的 path pieces too long and url safe base64 encoding处理路径片段过长与 URL 安全的 base64 编码以及多次出现的 windows quirks3.11.1、3.12.0Windows 特殊字符/路径兼容修复可见该模块的演进重点是跨平台健壮性。五、CI 环境识别isCI 与 getCINameisCI与getCIName在 1.0.17 版本加入CHANGELOGAdd isCI and getCIName。README 用法const { isCI, getCIName } require(gatsby-core-utils) if (isCI()) { // 执行 CI 专属代码 } const CI_NAME getCIName() // {CI_NAME: null} 或 {CI_NAME: Vercel}实现src/ci.ts不只是透传ci-info包而是按优先级尝试一串探测函数基于环境变量的检测NOW_BUILDER_ANNOTATE/NOW_REGIONZEIT Now、VERCEL_URL/VERCEL_BUILDERVercel Now、CODESANDBOX_SSECodeSandbox、CIRCLE_BRANCHCircleCI基于ci-info的检测ci.isCI与ci.nameCICI_NAME组合检测仅有CI环境变量时返回 CI detected without name。isCI()返回!!CINamegetCIName()在非 CI 环境返回null。README 中enhances isCI from ci-info with support for Vercel and Heroku detection正对应这段自定义探测逻辑——官方ci-info无法识别的新平台通过环境变量补全这也是 CHANGELOG 1.8.0/1.7.1 中improve github action and circle detection持续演进的方向。六、createMutex基于 LMDB 的跨进程互斥锁当多个 worker 或异步任务并发写同一文件例如多个并行构建进程同时写public目录时需要互斥控制。README 给出的用法const { createMutex } require(gatsby-core-utils/mutex) const mutex createMutex(my-custom-mutex-key) await mutex.acquire() await fs.writeFile(pathToFile, my custom content) await mutex.release()实现src/mutex.ts的关键在于锁不是内存变量而是持久化到LMDB 数据库getStorage(getDatabaseDir())默认轮询间隔DEFAULT_MUTEX_INTERVAL 3000mscreateMutex(key, timeout)的第二个参数可自定义重试间隔acquire通过storage.mutex.ifNoExists(key, ...)原子地写入LockStatus.Locked若已被占用则按间隔递归轮询等待key 会拼接构建 idBUILD_ID作为前缀保证不同构建之间的锁互不干扰releaseAllMutexes提供一键清空所有锁。CHANGELOG 3.8.0 的 create proper mutex 和 3.0.0 的 add fetch mutex for PQR 记录了该模块的引入而 1.3.1 的 create lock per service, rather than per site 则体现了按服务粒度隔离锁的设计修正。相关测试见 src/tests/mutex.ts。七、fetchRemoteFile可靠、可缓存的远程文件下载fetchRemoteFile是 Gatsby 图片/CDN 类 Source 插件下载远程资源的统一通道于 2.0.0 引入Add file download functions此后持续强化。核心实现见 src/fetch-remote-file.ts能力可归纳为五点1. 有界并发队列。所有下载请求经fastq队列串行调度默认并发数为GATSBY_CONCURRENT_DOWNLOAD环境变量默认 50const GATSBY_CONCURRENT_DOWNLOAD process.env.GATSBY_CONCURRENT_DOWNLOAD ? parseInt(process.env.GATSBY_CONCURRENT_DOWNLOAD, 10) || 0 : 502. 参数说明。IFetchRemoteFileOptions支持url、cache/directory目标目录、authhtaccess_user/htaccess_pass映射为 got 的 username/password对应 2.13.0 的 Switch auth option from got to username/password、httpHeaders、ext、name、cacheKey、excludeDigest等字段。注意cache与directory必须二选一否则抛错。3. 内容寻址目录与缓存。默认按createContentDigest(url)生成子目录excludeDigest可关闭文件名与扩展名可通过getRemoteFileName/getRemoteFileExtension从 URL 推断或由参数显式指定。4. ETag/304 增量更新。下载前读取上次保存的响应头storage.remoteFileInfo命中时带If-None-Match请求服务端返回 304 则清理临时文件并复用已有文件。CHANGELOG 3.3.0/3.2.0 的 handle 304 correctly between builds、3.9.0 的 fix caching when using remote-file、3.8.2 的 fix 304 when file does not exists 均围绕该机制修复边界情况。5. 重试与并发去重。3.2.0/3.1.1 的 Add retry on HTTP status codes tofetchRemoteFile 增加了基于 HTTP 状态码的重试同一 URL 的并发请求通过inFlightMap/buildId 记录在途文件去重避免重复下载cacheKey存在时还会在构建间复用已下载文件必要时从缓存目录复制到 public 目录复制过程同样用 mutex 串行化。底层 HTTP 请求封装见 src/remote-file-utils/fetch-file.ts测试见 src/tests/fetch-remote-file.js。CHANGELOG 中 4.1.0 的 decode uri-encode filename for remote file、2.4.0 的 download failure when missing content-length header、3.12.0 的 multiple requests with different outputdir 等修复都沉淀在这条下载链路上。八、哈希工具md5File、hash-wasm 重导出与 murmurhashgatsby-core-utils汇集了三种哈希能力1. hash-wasm 重导出。src/hash.ts 直接重导出md5、createMD5、sha256、sha1。该能力由 4.5.0 引入Add hashing methods from hash-wasmREADME 建议在输入较大时优先使用这类 WASM 实现they especially show their advantage on large inputs无需总是替换 Nodecrypto。2. md5File。对给定文件路径计算 MD5 hex 哈希src/md5-file.tsconst { md5File } require(gatsby-core-utils) await md5File(package.json)3. murmurhash。4.0.0 将murmurhash从别处迁入本包Move murmurhash to gatsby-core-utils见 src/murmurhash.ts用于对字符串做快速、短小的哈希典型场景是生成稳定且紧凑的标识符。此外 4.14.0 将hash-wasm升级到 ^4.11.0、3.2.0 将node-object-hash升级到 ^2.3.10均属于对底层哈希依赖的持续维护。九、其余常用工具一览除了上述重点模块CHANGELOG 与 src/index.ts 还揭示了其他实用工具及其引入时机isTruthysrc/is-truthy.ts把字符串配置值解析为布尔如true/12.0.0 从别处迁入Move isTruthy to gatsby-core-utils配套测试 src/tests/is-truthy.tsuuidsrc/uuid.ts统一 UUID 生成3.0.0 的 move away from old default uuid 记录了迁移旧默认 UUID 的变更site-metadatasrc/site-metadata.ts站点元数据读写1.3.15/1.3.16 引入并独立成函数Store site metadata、move site-metadata into its own function3.6.0/3.5.1 修复过其再导出问题Re-Export updateSiteMetadatapage-data / page-htmlsrc/page-data.ts、src/page-html.ts2.13.0 将 page-data 与 HTML 工具迁入本包Move page-data HTML utils to packageservice-lock / locksrc/service-lock.ts、src/lock.ts文件级服务锁listPluginssrc/list-plugins.ts读取站点插件列表3.6.0/3.5.2 修复过 plugin-add 功能Re-Add plugin-add functionalitygetConfigStore / getGatsbyVersion / getTermProgram / createRequireFromPath / getMatchPath / parse-component-path / readConfigFile等分别服务于配置存储、版本探测、终端程序检测、require 解析、路由匹配等构建期需求3.10.0 的 Allow write to gatsby-config.ts 与 add support for image-cdn 说明本包还持续支撑gatsby-config.ts与 Image CDN 等新特性的底层能力。十、版本演进时间线CHANGELOG 速览将 CHANGELOG.md 中具有功能意义的条目梳理成时间线可以直观看到该包的成长路径发布遵循 Conventional Commits 规范大量版本是 Version bump only 的纯发布记录版本时间关键变更1.0.02019-07-08创建gatsby-core-utils包1.0.172019-10-28新增isCI、getCIName1.0.222019-12-02使createContentDigest确定性deterministic1.3.62020-06-19修复 Buffer 的 hash 计算2.0.02021-03-02新增文件下载函数迁入isTruthy3.0.02021-10-21迁移默认 uuid为 PQR 添加 fetch mutex3.2.02021-11-16fetchRemoteFile支持按 HTTP 状态码重试正确处理 3043.8.02022-02-22改进fetch-remote-file创建正式的 mutex3.10.02022-03-16支持gatsby-config.ts支持 image-cdn3.12.02022-04-12修复路径片段过长与 URL 安全 base64Windows 兼容4.0.02022-11-08迁入murmurhash修正cpuCoreCount文档4.1.02022-11-22解码 URL 编码的远程文件名4.5.02023-01-24新增 hash-wasm 哈希方法md5/createMD5/sha256/sha14.13.02023-12-18重定向尊重force与conditions属性4.16.02026-01-26使用更明确的 Node.js 版本范围从这张表可以看出本包的两条演进主线一是能力聚合——isTruthy、murmurhash、page-data/html 等工具陆续从各处迁入避免循环依赖2.12.0 的 avoid circular imports二是可靠性强化——围绕远程文件下载重试、304、缓存、并发去重、临时文件清理、Windows 兼容与哈希确定性做了大量修复。十一、结语如何在你的 Gatsby 插件中复用这些工具gatsby-core-utils的设计哲学是把构建期的高频需求沉淀为可测试、可复用、跨平台一致的 API写 Source/Transformer 插件时用createContentDigest生成稳定节点标识用fetchRemoteFile下载远程资源而无需自己处理队列、重试与缓存需要控制并行度时用cpuCoreCount配合GATSBY_CPU_COUNT环境变量在 CI 中做条件分支时用isCI/getCIName识别 Vercel、CircleCI 等环境多 worker 写同一文件时用createMutex保证互斥。上述所有能力均有对应源码与测试可查源码目录、测试目录无论你是为 Gatsby 贡献插件还是深入构建管线的内部机制这个包都是理解 Gatsby 工程化基座的理想入口。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考