从 Git 仓库在 Gatsby Cloud 创建站点仓库导入、环境变量与部署访问完整指南【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby导读本文是 Gatsby 官方文档 Create a Site from a Repository 的深度展开版讲解如何把你现有的 Gatsby 项目从 Git 仓库导入 Gatsby Cloud并完成构建、预览与对外部署。读完本文你将掌握从「选择 Git 提供商」到「拿到默认托管域名」的完整链路并理解生产分支、基础目录、环境变量、私有构建 URL 等关键概念背后的设计意图与仓库依据。一、核心思路以 Git 仓库为站点源头Gatsby Cloud 允许你直接从一个 Git 仓库导入 Gatsby 项目并持续构建仓库成为站点内容与代码的唯一事实来源每次推送到分支都会自动触发对应环境的构建。这与传统的「本地上传产物」模型不同更接近主流的 CI/CD 工作流。整个流程可以概括为五步选择一个 Git 提供商GitHub / GitLab / Bitbucket并授权指定要导入的仓库及站点细节站点名、生产分支、基础目录按需连接 CMS 等集成配置环境变量构建完成后通过私有构建 URL 或默认域名访问站点。二、前置准备从一个可运行的 Starter 开始在导入之前你需要一个可构建的 Gatsby 项目。官方推荐使用gatsby-starter-blog作为起点在 GitHub 上打开该模板仓库点击Use this template按钮即可基于模板创建一个属于你自己的新仓库。这个 Starter 在当前仓库中也有对应的本地版本见 starters/blog。它的 gatsby-config.js 配置了siteMetadata含title、author、description、siteUrl等以及gatsby-plugin-image、gatsby-source-filesystem、gatsby-transformer-remark、gatsby-plugin-feed、gatsby-plugin-manifest等插件。其中siteUrl被 gatsby-plugin-feed 用来拼装 RSS 订阅地址可见站点元数据会在构建期被多种插件消费——这也是为什么「基础目录」和「站点配置」在导入时必须正确指定的原因之一。三、分步操作从仓库导入并构建站点1. 选择 Git 提供商并授权登录你的 Gatsby Cloud 仪表盘点击Add a Site添加站点按钮在 Import from a Git repository从 Git 仓库导入区域选择你的 Git 提供商并安装 Gatsby Cloud 应用以完成授权。本文以 GitHub 为例实际上GitLab 和 BitBucket 同样受支持。这里需要理解的关键点是授权安装的实质是让 Gatsby Cloud 获得读取你仓库内容的权限从而在每次推送时拉取最新代码并触发构建。2. 指定仓库细节站点名、生产分支与基础目录连接成功后找到你要导入的仓库并点击Import随后填写三项站点详情站点名Site name默认值为repo name-branch name即「仓库名-分支名」的组合分支Branch要导入的分支同时它会被设为 Gatsby Cloud 中的Production branch生产分支。示例中为main分支基础目录Base directory存放 Gatsby 站点的目录。如果你的仓库根目录就是站点最常见的情况保持默认的/即可若仓库采用 monorepo 结构、站点位于子目录如site/或apps/web/则在此指定相对路径。填写完毕后点击Next进入下一步。3. 添加可选集成CMS接下来系统会提示你连接可选的 CMS内容管理系统集成。这一步因 CMS 提供商而异——例如在 docs/docs 目录中就能看到大量针对特定数据源的接入文档如source-contentful、source-wordpress、source-sanity等示例与插件。具体到本文示例使用的 Starter由于gatsby-config.js中没有声明任何与云端集成相关的插件页面会显示 No supported integrations found未找到受支持的集成直接滚动跳过此卡片继续即可。判断「是否找到集成」的依据正是你仓库中 gatsby-config.js 里plugins数组声明的内容——Gatsby Cloud 会解析配置文件识别出可被云端集成的数据源插件。4. 配置环境变量随后会进入环境变量设置页面。环境变量的典型用途是把密钥类配置如 API Token、密钥注入到构建过程而无需把它们硬编码进源码。由于本示例的 Starter 不依赖任何环境变量页面显示为空直接点击Build Site构建站点继续即可。关于环境变量的完整玩法Build 变量 / Preview 变量、批量添加、代码中如何读取详见下文「环境变量深入解读」一节。5. 完成通过两种方式访问站点构建完成后你的站点可以在两个位置查看私有构建 URLPrivate Build URL使用构建 URL 可以预览本次构建部署的站点。该 URL不会被搜索引擎收录只能通过直接链接访问适合在正式对外发布前分享给团队评审。这类构建 URL 的格式属于统一托管Unified Hosting体系参见 统一托管说明生产构建与 PR 构建的 URL 形如build-{UUID}.gatsbyjs.io预览构建形如preview-{SITEPREFIX}.gatsbyjs.io历史上曾使用gtsb.io后缀旧 URL 仍然有效。公共默认域名Public default domainGatsby 托管Gatsby Hosting默认开启会为你的站点分配一个公共的 default domain默认域名在Site Settings Hosting站点设置 → 托管中可以查看。通过它可以直接访问对外发布的站点具体形式为YOUR_SITE_PREFIX.gatsbyjs.io并且默认启用 HTTPS。关于托管的更多细节可参考 部署到 Gatsby Cloud Hosting开启托管、首个部署等待页、修改站点前缀以更换默认域名等需要自定义域名时参见 为站点添加自定义域名。四、环境变量深入解读何时需要配置、如何生效虽然示例 Starter 跳过了这一步但真实项目几乎都会用到环境变量。Gatsby Cloud 的环境变量体系可参考仓库文档 管理环境变量要点如下入口Site Settings General Environment Variables站点设置 → 常规 → 环境变量两类环境Build variables构建变量作用于生产构建Production Builds与 PR 构建Pull Request BuildsPreview variables预览变量作用于 CMS 预览CMS Previews支持批量操作点击Bulk Copy Variables可整体复制点击Bulk Add Variables可按namevalue每行一条的格式批量添加批量添加不会覆盖已有变量而是追加之后可自行删除旧变量注意编辑环境变量会触发站点的一次新构建代码中读取通过process.env.变量名访问例如文档中给出的典型用法const contentfulConfig { spaceId: process.env.CONTENTFUL_SPACE_ID, accessToken: process.env.CONTENTFUL_ACCESS_TOKEN, } if (process.env.CONTENTFUL_HOST) { contentfulConfig.host process.env.CONTENTFUL_HOST }这正是「无需把密钥硬编码进源码」的实现机制密钥只存在于云端配置中构建时注入到process.env。五、排障GitHub 组织仓库授权问题从 GitHub 仓库创建站点时你需要完成 GitHub 授权。如果遇到无法授权或无法导入的情况按以下顺序排查先登出再重新登录。如果仍然无法导入且你的仓库隶属于某个 GitHub 组织、而你又不是该组织的所有者那么你可能没有足够的权限为组织安装 Gatsby Cloud 应用当导入组织仓库时系统会向该组织的所有者发送一封授权邮件。所有者通过邮件中的链接完成授权后你就能正常把仓库导入 Gatsby Cloud 了。六、相关资源本指南原文档create-site-from-repository.md环境变量配置管理环境变量托管与域名部署到 Gatsby Cloud Hosting、统一托管说明、添加自定义域名可参照的本地 Starterstarters/blog含 gatsby-config.js同目录下的其他 Cloud 操作指南how-to/cloud 目录如基于模板创建站点、部署 Functions、重定向与重写等【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/19 17:26:22 · 阅读 1.2k 从 Git 仓库在 Gatsby Cloud 创建站点：仓库导入、环境变量与部署访问完整指南
从 Git 仓库在 Gatsby Cloud 创建站点仓库导入、环境变量与部署访问完整指南【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby导读本文是 Gatsby 官方文档 Create a Site from a Repository 的深度展开版讲解如何把你现有的 Gatsby 项目从 Git 仓库导入 Gatsby Cloud并完成构建、预览与对外部署。读完本文你将掌握从「选择 Git 提供商」到「拿到默认托管域名」的完整链路并理解生产分支、基础目录、环境变量、私有构建 URL 等关键概念背后的设计意图与仓库依据。一、核心思路以 Git 仓库为站点源头Gatsby Cloud 允许你直接从一个 Git 仓库导入 Gatsby 项目并持续构建仓库成为站点内容与代码的唯一事实来源每次推送到分支都会自动触发对应环境的构建。这与传统的「本地上传产物」模型不同更接近主流的 CI/CD 工作流。整个流程可以概括为五步选择一个 Git 提供商GitHub / GitLab / Bitbucket并授权指定要导入的仓库及站点细节站点名、生产分支、基础目录按需连接 CMS 等集成配置环境变量构建完成后通过私有构建 URL 或默认域名访问站点。二、前置准备从一个可运行的 Starter 开始在导入之前你需要一个可构建的 Gatsby 项目。官方推荐使用gatsby-starter-blog作为起点在 GitHub 上打开该模板仓库点击Use this template按钮即可基于模板创建一个属于你自己的新仓库。这个 Starter 在当前仓库中也有对应的本地版本见 starters/blog。它的 gatsby-config.js 配置了siteMetadata含title、author、description、siteUrl等以及gatsby-plugin-image、gatsby-source-filesystem、gatsby-transformer-remark、gatsby-plugin-feed、gatsby-plugin-manifest等插件。其中siteUrl被 gatsby-plugin-feed 用来拼装 RSS 订阅地址可见站点元数据会在构建期被多种插件消费——这也是为什么「基础目录」和「站点配置」在导入时必须正确指定的原因之一。三、分步操作从仓库导入并构建站点1. 选择 Git 提供商并授权登录你的 Gatsby Cloud 仪表盘点击Add a Site添加站点按钮在 Import from a Git repository从 Git 仓库导入区域选择你的 Git 提供商并安装 Gatsby Cloud 应用以完成授权。本文以 GitHub 为例实际上GitLab 和 BitBucket 同样受支持。这里需要理解的关键点是授权安装的实质是让 Gatsby Cloud 获得读取你仓库内容的权限从而在每次推送时拉取最新代码并触发构建。2. 指定仓库细节站点名、生产分支与基础目录连接成功后找到你要导入的仓库并点击Import随后填写三项站点详情站点名Site name默认值为repo name-branch name即「仓库名-分支名」的组合分支Branch要导入的分支同时它会被设为 Gatsby Cloud 中的Production branch生产分支。示例中为main分支基础目录Base directory存放 Gatsby 站点的目录。如果你的仓库根目录就是站点最常见的情况保持默认的/即可若仓库采用 monorepo 结构、站点位于子目录如site/或apps/web/则在此指定相对路径。填写完毕后点击Next进入下一步。3. 添加可选集成CMS接下来系统会提示你连接可选的 CMS内容管理系统集成。这一步因 CMS 提供商而异——例如在 docs/docs 目录中就能看到大量针对特定数据源的接入文档如source-contentful、source-wordpress、source-sanity等示例与插件。具体到本文示例使用的 Starter由于gatsby-config.js中没有声明任何与云端集成相关的插件页面会显示 No supported integrations found未找到受支持的集成直接滚动跳过此卡片继续即可。判断「是否找到集成」的依据正是你仓库中 gatsby-config.js 里plugins数组声明的内容——Gatsby Cloud 会解析配置文件识别出可被云端集成的数据源插件。4. 配置环境变量随后会进入环境变量设置页面。环境变量的典型用途是把密钥类配置如 API Token、密钥注入到构建过程而无需把它们硬编码进源码。由于本示例的 Starter 不依赖任何环境变量页面显示为空直接点击Build Site构建站点继续即可。关于环境变量的完整玩法Build 变量 / Preview 变量、批量添加、代码中如何读取详见下文「环境变量深入解读」一节。5. 完成通过两种方式访问站点构建完成后你的站点可以在两个位置查看私有构建 URLPrivate Build URL使用构建 URL 可以预览本次构建部署的站点。该 URL不会被搜索引擎收录只能通过直接链接访问适合在正式对外发布前分享给团队评审。这类构建 URL 的格式属于统一托管Unified Hosting体系参见 统一托管说明生产构建与 PR 构建的 URL 形如build-{UUID}.gatsbyjs.io预览构建形如preview-{SITEPREFIX}.gatsbyjs.io历史上曾使用gtsb.io后缀旧 URL 仍然有效。公共默认域名Public default domainGatsby 托管Gatsby Hosting默认开启会为你的站点分配一个公共的 default domain默认域名在Site Settings Hosting站点设置 → 托管中可以查看。通过它可以直接访问对外发布的站点具体形式为YOUR_SITE_PREFIX.gatsbyjs.io并且默认启用 HTTPS。关于托管的更多细节可参考 部署到 Gatsby Cloud Hosting开启托管、首个部署等待页、修改站点前缀以更换默认域名等需要自定义域名时参见 为站点添加自定义域名。四、环境变量深入解读何时需要配置、如何生效虽然示例 Starter 跳过了这一步但真实项目几乎都会用到环境变量。Gatsby Cloud 的环境变量体系可参考仓库文档 管理环境变量要点如下入口Site Settings General Environment Variables站点设置 → 常规 → 环境变量两类环境Build variables构建变量作用于生产构建Production Builds与 PR 构建Pull Request BuildsPreview variables预览变量作用于 CMS 预览CMS Previews支持批量操作点击Bulk Copy Variables可整体复制点击Bulk Add Variables可按namevalue每行一条的格式批量添加批量添加不会覆盖已有变量而是追加之后可自行删除旧变量注意编辑环境变量会触发站点的一次新构建代码中读取通过process.env.变量名访问例如文档中给出的典型用法const contentfulConfig { spaceId: process.env.CONTENTFUL_SPACE_ID, accessToken: process.env.CONTENTFUL_ACCESS_TOKEN, } if (process.env.CONTENTFUL_HOST) { contentfulConfig.host process.env.CONTENTFUL_HOST }这正是「无需把密钥硬编码进源码」的实现机制密钥只存在于云端配置中构建时注入到process.env。五、排障GitHub 组织仓库授权问题从 GitHub 仓库创建站点时你需要完成 GitHub 授权。如果遇到无法授权或无法导入的情况按以下顺序排查先登出再重新登录。如果仍然无法导入且你的仓库隶属于某个 GitHub 组织、而你又不是该组织的所有者那么你可能没有足够的权限为组织安装 Gatsby Cloud 应用当导入组织仓库时系统会向该组织的所有者发送一封授权邮件。所有者通过邮件中的链接完成授权后你就能正常把仓库导入 Gatsby Cloud 了。六、相关资源本指南原文档create-site-from-repository.md环境变量配置管理环境变量托管与域名部署到 Gatsby Cloud Hosting、统一托管说明、添加自定义域名可参照的本地 Starterstarters/blog含 gatsby-config.js同目录下的其他 Cloud 操作指南how-to/cloud 目录如基于模板创建站点、部署 Functions、重定向与重写等【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考