Skip to main content

How Gatsby Works with GitHub Pages

GitHub页面是GitHub提供的一项服务,允许托管直接从存储库配置的网站. Gatsby网站可以托管在GitHub页面上,只需对代码库和存储库的设置进行一些配置即可.

您可以通过几种不同的方式在GitHub页面上发布站点:

  • 到类似username.github.io/reponame//docs的路径
  • 到基于您的用户名或组织名称的子域: username.github.ioorgname.github.io
  • 到位于username.github.io的根子域,然后配置为使用自定义域

Configuring the GitHub Pages source branch

您必须从GitHub中的存储库设置中选择要部署的分支,以使GitHub页面正常运行. 在GitHub上:

  1. 导航到站点的存储库.

  2. 在存储库名称下,单击设置.

  3. 在GitHub Pages部分中,使用Source下拉列表选择master(用于发布到根子域)或gh-pages(用于发布到类似/docs的路径)作为GitHub Pages发布源.

  4. 单击保存.

Installing the gh-pages package

将Gatsby应用程序推送到GitHub Pages的最简单方法是使用一个名为gh-pages的软件包.

npm install gh-pages --save-dev

Using a deploy script

package.json自定义脚本使您可以更轻松地构建网站并将构建文件的内容移动到GitHub页面的适当分支,这有助于自动化该过程.

Deploying to a path on GitHub pages

对于部署在诸如username.github.io/reponame/--prefix-paths的站点,将使用--prefix-paths标志,因为您的网站最终将位于诸如username.github.io/reponame/类的文件夹中. 您需要将/reponame 路径前缀添加为gatsby-config.js的选项:

gatsby-config.js
module.exports = {
pathPrefix: "/reponame",
}

然后在存储库的代码库中将deploy脚本添加到package.json

package.json
{
"scripts": {
"deploy": "gatsby build --prefix-paths && gh-pages -d public"
}
}

当您运行npm run deploy的所有内容public文件夹将被移动到存储库的gh-pages分支. 确保您的存储库设置已将gh-pages分支设置为要从中进行部署的源.

注意 :要选择母版页或gh-pages作为发布源,您的存储库中必须存在分支. 如果您没有master或gh-pages分支,则可以创建它们,然后返回源设置来更改发布源.

Deploying to a GitHub pages subdomain at github.io

对于名为username.github.io的存储库,您无需指定pathPrefix并且您的网站需要推送到master分支.

package.json
{
"scripts": {
"deploy": "gatsby build && gh-pages -d public -b master"
}
}

运行npm run deploy您应该在username.github.io看到您的网站.

Deploying to the root subdomain and using a custom domain

如果您使用自定义域 ,请不要添加pathPrefix因为它会破坏您网站上的导航. 仅当站点不在存储库站点等域的根目录中时,才需要路径前缀.

注意 :不要忘记将CNAME文件添加到static目录中.

Deploying to GitHub pages from a CI server

也可以通过CI服务器将您的网站部署到gh-pages . 该示例使用Travis CI(托管的持续集成服务),但是其他CI系统也可以正常工作.

您可以使用gh-pages npm模块进行部署. 但是首先,您需要使用适当的凭据配置它,以便gh-pages可以推送新分支.

Obtain a GitHub token for authenticating with CI

要将更改从CI系统推送到GitHub,您需要进行身份验证. 建议使用GitHub开发人员令牌 .

In GitHub go to your account settings -> Developer settings -> Personal access tokens, and create a new token that provides the repo access permissions.

存储库的Travis设置中 ,添加一个新的秘密环境变量,名称为GH_TOKEN ,其中包含从GitHub复制的令牌的值. 确保不要将"在构建日志中显示"设置切换为开,因为令牌应保持秘密状态. 否则,陌生人将能够推送到您的存储库(一个重大的安全问题).

Add script to deploy to GitHub Pages via CI

更新Gatsby项目的package.json以包含一个deploy运行脚本,该脚本使用两个重要的命令行参数调用gh-pages

  1. -d public指定构建文件所在的目录,并将其作为源推送到GitHub页面
  2. -r URL -GitHub存储库URL,包括使用秘密GitHub令牌(作为秘密环境变量)以将更改推送到gh-pages分支,形式为https://$GH_TOKEN@github.com/<github username>/<github repository name>.git

这是一个示例(请确保将用户名和存储库名称更新为您自己的名称):

"scripts": {
"deploy": "gatsby build --prefix-paths && gh-pages -d public -r https://$GH_TOKEN@github.com/lirantal/dockly.git"
}

Update .travis.yml configuration

以下.travis.yml配置提供了参考:

language: node_js
before_script:
- npm install -g gatsby-cli
node_js:
- "10"
deploy:
provider: script
# Note: change "docs" to the directory where your gatsby-site lives, if necessary
script: cd docs/ && yarn install && yarn run deploy
skip_cleanup: true
on:
branch: master

要在此处分解有关将Gatsby网站从Travis部署到GitHub页面的重要信息:

  1. before_script用于安装Gatsby CLI,因此可以在项目的运行脚本中使用它来构建Gatsby网站
  2. 仅当构建在master分支上运行时, deploy才会触发,在这种情况下,它将触发部署脚本. 在上面的示例中,Gatsby站点位于docs/目录中. 该脚本将切换到该目录,安装所有网站依赖项,并按照上一步中的设置运行部署脚本.

.travis.ymlpackage.json文件提交并推送到您的基本分支将是该过程的最后一步.


Edit this page on GitHub
Docs
Tutorials
Plugins
Blog
Showcase

by  ICOPY.SITE