Gatsby Cloud Monorepo 支持指南受支持工具、兼容性等级与 PnP 故障排查【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby导读本指南以 docs/docs/reference/cloud/monorepos.md 为骨架系统讲解 Gatsby Cloud 对 Monorepo 工程结构的支持范围。你将了解 Yarn Workspaces、Lerna、NPM Workspaces、NX 等工具在 Gatsby Cloud 上的支持等级掌握 PlugnPlayPnP环境下的兼容性判断方法并学会通过.yarnrc.yml中的nodeLinker配置解决依赖解析问题从而放心地把多包仓库接入 Gatsby Cloud 构建。为什么需要关注 Monorepo 支持Monorepo单体仓库将多个独立项目、包或站点的代码放在同一个 Git 仓库中统一管理。Gatsby Cloud 支持以 Monorepo 形式组织的项目但市面上存在多种相互竞争的 Monorepo 构建工具不同工具在依赖安装、链接方式与构建管线上的差异很大因此明确 Gatsby Cloud 当前实际支持哪些工具是决定你的仓库能否被平台正确识别、构建和部署的关键前提。值得一提的是Gatsby 自身的核心代码库就是一个典型的 Monorepo根目录的 package.json 声明了workspaces: [packages/*]与packageManager: yarn1.22.19lerna.json 则配置了 Lerna 与 Yarn Workspaces 的协同使用。也就是说你在自己的 Monorepo 中使用的工具组合与 Gatsby 团队日常构建本项目所用的方案高度同源这为下文所述支持矩阵提供了现实印证。支持等级图例在阅读工具支持表之前先明确图例含义图标能力等级●完全支持Fully Supported◐部分支持Somewhat Supported支持程度最小化○不支持Not Supported工具支持矩阵以下表格列出了 Gatsby Cloud 对各类 Monorepo 工具的支持情况工具支持等级说明Yarn Workspacesv1●完全支持Yarn Workspacesv2/v3 PnP◐部分支持Lerna●完全支持NPM Workspacesv7 及更高版本●完全支持NX●完全支持依赖检测与安装Turborepo○当前暂无支持计划pnpm○暂不支持逐工具解读与仓库佐证Yarn Workspacesv1完全支持Yarn v1 的 Workspaces 是当前最成熟、使用最广泛的 Monorepo 方案之一Gatsby Cloud 对其提供完全支持。Yarn Workspaces 通过根目录package.json的workspaces字段声明包目录将各子包的依赖统一提升hoist到根node_modules既减少了重复安装也让跨包引用变得简单。这一模式在 Gatsby 仓库中得到完整实践根 package.json 中的workspaces: [packages/*]将所有packages/目录下的包纳入统一管理同时engines字段声明了yarn: ^1.17.3、node: 18.0.0 26、npm: 8.0.0的运行前提。如果你在本地复刻这种结构yarn install后即可在子包之间通过包名相互引用Gatsby Cloud 会在云端重复这一安装流程。Yarn Workspacesv2/v3 PnP部分支持Yarn v2/v3 引入了 PlugnPlayPnP机制不再生成node_modules目录而是通过.pnp.cjs文件精确描述依赖位置。Gatsby Cloud 对此仅提供最小化支持因此在 PnP 环境下可能遇到依赖解析不兼容的问题详见下文「故障排查」。从 Gatsby 构建侧的源码看Gatsby 对 PnP 场景有专门的适配逻辑cache-folder-resolver.ts 顶部注释明确写道「To support Yarn PNP and pnpm we have to make sure dependencies resolved from …」为支持 Yarn PnP 与 pnpm必须确保依赖的解析来源正确并在运行时检测process.versions.pnp来决定是否启用对应插件test-import-error.ts 也会针对err.pnpCode QUALIFIED_PATH_RESOLUTION_FAILED这类 PnP 专有错误码做特殊处理。这些源码表明PnP 并非无法工作但其依赖解析路径与经典node_modules模式存在本质差异这正是它只被标注为「部分支持」的深层原因。相关行为在 load-themes 测试 中也有覆盖模拟 yarn PnP / pnpm 下主题与插件未被提升到根node_modules的场景。Lerna完全支持Lerna 是经典的多包管理工具常与 Yarn Workspaces 搭配使用。Gatsby Cloud 对 Lerna 提供完全支持。Gatsby 仓库本身即采用「Lerna Yarn Workspaces」组合lerna.json 中packages: [packages/*]、npmClient: yarn、useWorkspaces: true同时在根package.json的 scripts 中大量使用lerna run、lerna publish等命令见 package.json 的bootstrap、watch、publish-release等脚本。这种成熟组合在云端同样可以被稳定识别。NPM Workspacesv7 及更高版本完全支持从 npm v7 开始npm 原生支持 Workspaces 字段语法与 Yarn Workspaces 保持一致。Gatsby Cloud 对使用npm workspaces的仓库提供完全支持。需要留意的是Gatsby 根 package.json 的engines中声明了npm: 8.0.0也就是说在本地使用 NPM Workspaces 时也应确保 npm 版本不低于 7推荐使用与 Gatsby 一致的 npm 8 及以上版本以获得更稳定的行为。NX完全支持NX 是当前主流的 Monorepo 编排工具Gatsby Cloud 对其提供完全支持尤其是依赖检测dependency detection与安装环节。NX 下通常使用 NPM 或 Yarn Workspaces 作为底层依赖管理器Gatsby Cloud 可以正确识别并完成依赖安装。Turborepo暂不支持Gatsby Cloud 当前不支持 Turborepo且暂无支持计划。如果你的仓库使用 Turborepo 编排任务需要先调整依赖管理与构建入口才能接入 Gatsby Cloud 构建。pnpm暂不支持Gatsby Cloud 同样不支持 pnpm。注意这不代表 Gatsby 本身无法感知 pnpm 的存在——上文提到的 cache-folder-resolver.ts 会检测node_modules/.pnpm目录结构与NODE_PATH环境变量来适配 pnpm 的依赖布局其注释与逻辑明确覆盖 pnpm 场景。但平台层面的 Monorepo 支持矩阵中pnpm 仍处于未支持状态。故障排查PnP 与 Yarn 的兼容性问题问题本质PlugnPlay 改变了 Node 依赖解析的默认机制不再通过磁盘上的node_modules物理目录查找模块而是依赖.pnp.cjs进行虚拟解析。部分工具、原生模块或依赖硬编码路径的库在 PnP 环境下无法正常工作这也是 Yarn 官方维护了一份 PnP「兼容性表」的原因。推荐解法启用 node-modules 插件如果你在 Gatsby Cloud或其他 Yarn v2/v3 环境中遇到 PnP 相关的解析失败、模块找不到等错误最直接的解决方式是让 Yarn 回退到经典的node_modules链接模式。在运行全新的yarn install之前在你的本地.yarnrc.yml文件中加入以下配置nodeLinker: node-modules配置要点nodeLinker是 Yarn v2/v3 的核心配置项node-modules值会启用 Yarn 内置的node-modules插件使安装行为接近 Yarn v1 / npm 的物理目录模式该配置应在删除旧的安装产物后、首次执行新的yarn install之前写入以保证链接模式从头生效建议同时清理.yarn/cache、.pnp.cjs与node_modules等由 PnP 模式生成的产物修改后请重新提交.yarnrc.yml并推送Gatsby Cloud 拉取代码后会依据该配置重新安装依赖。本地验证建议在将改动推到云端之前可以在本地按下列步骤验证确认仓库根目录与子包均符合 Yarn Workspaces 的目录约定根package.json声明workspaces写入上述.yarnrc.yml后执行yarn install观察是否生成常规node_modules目录本地执行yarn build或通过gatsby-cli执行构建确认无 PnP 相关的模块解析报错再推送至 Gatsby Cloud 触发构建。结论完全支持Yarn Workspacesv1、Lerna、NPM Workspacesv7、NX部分支持Yarn Workspacesv2/v3 PnP遇到兼容性问题可通过.yarnrc.yml的nodeLinker: node-modules回退到经典模式暂不支持Turborepo、pnpm。在规划 Gatsby Cloud 项目时建议优先选择完全支持的工具组合若必须使用 PnP请参照本指南的故障排查步骤先行验证。Gatsby 自身「Yarn Workspaces v1 Lerna」的仓库结构见 package.json 与 lerna.json是这套受支持组合在真实大规模项目中的直接样板可作为你搭建 Monorepo 时的参照。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gatsby Cloud Monorepo 支持指南：受支持工具、兼容性等级与 PnP 故障排查
Gatsby Cloud Monorepo 支持指南受支持工具、兼容性等级与 PnP 故障排查【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby导读本指南以 docs/docs/reference/cloud/monorepos.md 为骨架系统讲解 Gatsby Cloud 对 Monorepo 工程结构的支持范围。你将了解 Yarn Workspaces、Lerna、NPM Workspaces、NX 等工具在 Gatsby Cloud 上的支持等级掌握 PlugnPlayPnP环境下的兼容性判断方法并学会通过.yarnrc.yml中的nodeLinker配置解决依赖解析问题从而放心地把多包仓库接入 Gatsby Cloud 构建。为什么需要关注 Monorepo 支持Monorepo单体仓库将多个独立项目、包或站点的代码放在同一个 Git 仓库中统一管理。Gatsby Cloud 支持以 Monorepo 形式组织的项目但市面上存在多种相互竞争的 Monorepo 构建工具不同工具在依赖安装、链接方式与构建管线上的差异很大因此明确 Gatsby Cloud 当前实际支持哪些工具是决定你的仓库能否被平台正确识别、构建和部署的关键前提。值得一提的是Gatsby 自身的核心代码库就是一个典型的 Monorepo根目录的 package.json 声明了workspaces: [packages/*]与packageManager: yarn1.22.19lerna.json 则配置了 Lerna 与 Yarn Workspaces 的协同使用。也就是说你在自己的 Monorepo 中使用的工具组合与 Gatsby 团队日常构建本项目所用的方案高度同源这为下文所述支持矩阵提供了现实印证。支持等级图例在阅读工具支持表之前先明确图例含义图标能力等级●完全支持Fully Supported◐部分支持Somewhat Supported支持程度最小化○不支持Not Supported工具支持矩阵以下表格列出了 Gatsby Cloud 对各类 Monorepo 工具的支持情况工具支持等级说明Yarn Workspacesv1●完全支持Yarn Workspacesv2/v3 PnP◐部分支持Lerna●完全支持NPM Workspacesv7 及更高版本●完全支持NX●完全支持依赖检测与安装Turborepo○当前暂无支持计划pnpm○暂不支持逐工具解读与仓库佐证Yarn Workspacesv1完全支持Yarn v1 的 Workspaces 是当前最成熟、使用最广泛的 Monorepo 方案之一Gatsby Cloud 对其提供完全支持。Yarn Workspaces 通过根目录package.json的workspaces字段声明包目录将各子包的依赖统一提升hoist到根node_modules既减少了重复安装也让跨包引用变得简单。这一模式在 Gatsby 仓库中得到完整实践根 package.json 中的workspaces: [packages/*]将所有packages/目录下的包纳入统一管理同时engines字段声明了yarn: ^1.17.3、node: 18.0.0 26、npm: 8.0.0的运行前提。如果你在本地复刻这种结构yarn install后即可在子包之间通过包名相互引用Gatsby Cloud 会在云端重复这一安装流程。Yarn Workspacesv2/v3 PnP部分支持Yarn v2/v3 引入了 PlugnPlayPnP机制不再生成node_modules目录而是通过.pnp.cjs文件精确描述依赖位置。Gatsby Cloud 对此仅提供最小化支持因此在 PnP 环境下可能遇到依赖解析不兼容的问题详见下文「故障排查」。从 Gatsby 构建侧的源码看Gatsby 对 PnP 场景有专门的适配逻辑cache-folder-resolver.ts 顶部注释明确写道「To support Yarn PNP and pnpm we have to make sure dependencies resolved from …」为支持 Yarn PnP 与 pnpm必须确保依赖的解析来源正确并在运行时检测process.versions.pnp来决定是否启用对应插件test-import-error.ts 也会针对err.pnpCode QUALIFIED_PATH_RESOLUTION_FAILED这类 PnP 专有错误码做特殊处理。这些源码表明PnP 并非无法工作但其依赖解析路径与经典node_modules模式存在本质差异这正是它只被标注为「部分支持」的深层原因。相关行为在 load-themes 测试 中也有覆盖模拟 yarn PnP / pnpm 下主题与插件未被提升到根node_modules的场景。Lerna完全支持Lerna 是经典的多包管理工具常与 Yarn Workspaces 搭配使用。Gatsby Cloud 对 Lerna 提供完全支持。Gatsby 仓库本身即采用「Lerna Yarn Workspaces」组合lerna.json 中packages: [packages/*]、npmClient: yarn、useWorkspaces: true同时在根package.json的 scripts 中大量使用lerna run、lerna publish等命令见 package.json 的bootstrap、watch、publish-release等脚本。这种成熟组合在云端同样可以被稳定识别。NPM Workspacesv7 及更高版本完全支持从 npm v7 开始npm 原生支持 Workspaces 字段语法与 Yarn Workspaces 保持一致。Gatsby Cloud 对使用npm workspaces的仓库提供完全支持。需要留意的是Gatsby 根 package.json 的engines中声明了npm: 8.0.0也就是说在本地使用 NPM Workspaces 时也应确保 npm 版本不低于 7推荐使用与 Gatsby 一致的 npm 8 及以上版本以获得更稳定的行为。NX完全支持NX 是当前主流的 Monorepo 编排工具Gatsby Cloud 对其提供完全支持尤其是依赖检测dependency detection与安装环节。NX 下通常使用 NPM 或 Yarn Workspaces 作为底层依赖管理器Gatsby Cloud 可以正确识别并完成依赖安装。Turborepo暂不支持Gatsby Cloud 当前不支持 Turborepo且暂无支持计划。如果你的仓库使用 Turborepo 编排任务需要先调整依赖管理与构建入口才能接入 Gatsby Cloud 构建。pnpm暂不支持Gatsby Cloud 同样不支持 pnpm。注意这不代表 Gatsby 本身无法感知 pnpm 的存在——上文提到的 cache-folder-resolver.ts 会检测node_modules/.pnpm目录结构与NODE_PATH环境变量来适配 pnpm 的依赖布局其注释与逻辑明确覆盖 pnpm 场景。但平台层面的 Monorepo 支持矩阵中pnpm 仍处于未支持状态。故障排查PnP 与 Yarn 的兼容性问题问题本质PlugnPlay 改变了 Node 依赖解析的默认机制不再通过磁盘上的node_modules物理目录查找模块而是依赖.pnp.cjs进行虚拟解析。部分工具、原生模块或依赖硬编码路径的库在 PnP 环境下无法正常工作这也是 Yarn 官方维护了一份 PnP「兼容性表」的原因。推荐解法启用 node-modules 插件如果你在 Gatsby Cloud或其他 Yarn v2/v3 环境中遇到 PnP 相关的解析失败、模块找不到等错误最直接的解决方式是让 Yarn 回退到经典的node_modules链接模式。在运行全新的yarn install之前在你的本地.yarnrc.yml文件中加入以下配置nodeLinker: node-modules配置要点nodeLinker是 Yarn v2/v3 的核心配置项node-modules值会启用 Yarn 内置的node-modules插件使安装行为接近 Yarn v1 / npm 的物理目录模式该配置应在删除旧的安装产物后、首次执行新的yarn install之前写入以保证链接模式从头生效建议同时清理.yarn/cache、.pnp.cjs与node_modules等由 PnP 模式生成的产物修改后请重新提交.yarnrc.yml并推送Gatsby Cloud 拉取代码后会依据该配置重新安装依赖。本地验证建议在将改动推到云端之前可以在本地按下列步骤验证确认仓库根目录与子包均符合 Yarn Workspaces 的目录约定根package.json声明workspaces写入上述.yarnrc.yml后执行yarn install观察是否生成常规node_modules目录本地执行yarn build或通过gatsby-cli执行构建确认无 PnP 相关的模块解析报错再推送至 Gatsby Cloud 触发构建。结论完全支持Yarn Workspacesv1、Lerna、NPM Workspacesv7、NX部分支持Yarn Workspacesv2/v3 PnP遇到兼容性问题可通过.yarnrc.yml的nodeLinker: node-modules回退到经典模式暂不支持Turborepo、pnpm。在规划 Gatsby Cloud 项目时建议优先选择完全支持的工具组合若必须使用 PnP请参照本指南的故障排查步骤先行验证。Gatsby 自身「Yarn Workspaces v1 Lerna」的仓库结构见 package.json 与 lerna.json是这套受支持组合在真实大规模项目中的直接样板可作为你搭建 Monorepo 时的参照。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考