木匣子

Web/Game/Programming/Life etc.

使用 Github Pages 托管主页

「所码即所得」一文中我创建了一个小项目。该项目构建后会生成一个静态页面:

  • 一个网页:index.html
  • 一个样式表:bundle.css
  • 和一个脚本:bundle.js

原先我将他们与博客一起托管在自己的 EC2 上面,但是由于现在我将整个博客都用 hexo 引擎静态化并放到 s3 上,不必再支付昂贵的 EC2 实例费用了。于是我打算将首页也搬走。

搬到哪去呢?我可以将主页也放到 s3 上。或者直接使用 Github Pages 服务。因为正好这个项目在 Github 上是开源的,所以可以免费使用 Github Pages 服务来托管项目页面。

GH-Pages

简单介绍一下 Github Pages 。这是一项 Github 推出的免费服务(对私有仓库是收费的)。只要通过一些简单的规则,你就可以为托管在 Github 的项目创建在线页面。

Github Pages 分为「个人/组织页面」以及「项目页面」两种,前者用于展示个人信息,适用于个人主页、简历或博客。后种可以用来介绍项目,提供文档,或展示 Demo 等。

Personal Page

假设你有一个 github 帐号:https://github.com/mutoo,如果你想要创建个人页面,只需要创建一个仓库:https://github.com/mutoo/mutoo.github.io 然后提交静态页面到该仓库的 master 分支下。所有的内容都会被托管到这个地址:https://mutoo.github.io (建议开启强制 https)

Project Page

如果你有一个项目:https://github.com/mutoo/self-printing-homepage,则有几种方式可以使用 GH-Pages 托管面页:

  1. 直接使用 master 分支,常用于静态 Web 项目;
  2. 可以在项目的 master 分支下创建一个 /doc 目录,将静态页面放在该目录,常用于文档;
  3. 或创始一个 gh-pages 分支,将静态页面放在根目录,常用于静态生成博客;

以上几种方法都会将页面托管至 https://mutoo.github.io/self-printing-homepage 但需要在后台选定其中一种方式作为源。

Custom Domain

此外,你可以为 Github Page 绑定自定义域名,只需要在项目设置中填入域名,然后将域名指向 gh-pages 的服务器即可,详细文档可以参见这里。这里作一下简单的笔记:

  • 绑定 APEX 域名(即根域名,如:mutoo.im):如果服务器支持 Alias 记录,可以直接创建一个,并指向原 gh-pages domain,例如 mutoo.github.io。如果不支持,则使用 A 记录,指向以下 IP 即可:
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
此外要注意的就是只有「个人/组织页面」支持绑定 APEX 域名。
  • 绑定子域名:如 project.mutoo.im 可以直接使用 CNAME 记录指向 gh-pages domain 。

我需要绑定的是 APEX 域名,而我使用的 Name Server 是 AWS 的 Route53,虽然支持 Alias 记录,但是只能在 AWS 自有的服务上使用,所以选择了 A 记录绑定的方式。

绑定好域名后,github 还会自动为你生成 https 证书,这一过程是自动而且免费的,只需要耐心等待几分钟。比起自己用 Let’s encrypt 折腾证书来说真是相当省心。

注意:绑定域名后,会在目录中产生一个 CNAME 的文件。

若为个人页面绑定了域名 mutoo.im,则无须为项目页面另作设置。项目页面会自动绑定到 mutoo.im/<project-name> 目录中。不过也可以单独为项目绑定另外的域名。

Update & Deploy

理解了 Github Pages 的业务规则后,需要考虑一下自己的需求了:

  • 项目放在 mutoo/self-printing-page
  • 主页放在 mutoo/mutoo.github.io
  • 主页需要绑定域名 mutoo.im

由于项目放在两个不同的仓库中,更新的时候在一个仓库修改源码,然后发布的时候,生成的文件需要导入到另一个仓库。

对于这样的需求,我有几个选择:

  1. 使用持续集成系统,例如 ‎Travis CI,它对 github 上的开源项目是免费的。当 self-printing-page 仓库有新的推送的时候,持续集成系统负责将其编译,测试通过后部署到 mutoo.github.io 仓库中去。
  2. 使用 git subtree 或者 git submodules 来管理项目。将 mutoo.github.io 作为 self-printing-page 仓库的一个子目录(/dist),编译时直接发布到该目录中去。

方案一对于我这个小项目来说有点大炮打蚊子了。所以我选择方案二。那么问题又来了,是用 git subtree 还是 git submodules 来管理两个项目?

Subtree

git subtree 的历史比较早,它将子目录与目标仓库绑定,并将添加进来的文件与一般文件一起加入当前的仓库,更新的时候可以从目标仓库拉取最新版本。但如果想将本仓库所作的更改推送到目标仓库,是一件非常麻烦的事。

Submodules

git submodules 是后起之秀,它将子目录作为目标仓库的根目录,目录中的文件单独为作一个仓库进行管理。子目录中的内容可以独立更新和推送,非常灵活。

综上,若要将 mutoo.github.io 仓库作为 self-printing-page 的子目录,而主要操作是用于发布和推送,且不需要拉取。所以还是选择 submodules 进行管理更合适。

方案二虽然没有方案一那么自动化,更新的时候需要同时推送两个仓库。不过对于现代 IDE来说(我用的 PhpStore),也是一键就能完成的事。

至此,主页已经能够放在 Github Pages 上稳定运作了。再放个五六年不管应该也没啥问题,233。