当前位置：文江博客文章教程详情

使用 github pages 快速部署你的静态网页

发布于 2024-09-24 12:39:23 字数 9020 浏览 64 评论 0

在日常工作中，我们经常会遇到要做 demo 展示的情况. 做 demo 展示不同于做项目开发，我们需要的是快速轻便的开发和部署，而不是完备的一整套开发流程。下图肯定不是我们做一个 demo 想要的流程。

deploy_by_you_own

尤其对于数据可视化工作，能快速的创建一个 demo 来验证自己的想法，并且方便的和同伴分享自己作品是非常重要的。
在这里给大家介绍一种笔者经常用来做 demo 的方法: Github Pages .

选择 github pages 的理由

使用零成本: github pages 集成在 github 中，直接和代码管理绑定在一起，随着代码更新自动重新部署，使用非常方便。
免费: 免费提供 username.github.io 的域名，免费的静态网站服务器。
无数量限制: github pages 没有使用的数量限制，每一个 github repository 都可以部署为一个静态网站。

使用方法

一. 部署静态网页

首先我们介绍一下部署最基础的静态网页，最终的效果是展示出一个 Hello, github pages :) 页面。

demo 地址: github repository
github page 地址: https://ssthouse.github.io/github-pages-demo/

1.1 创建一个 github 项目

前往 github 官网 , 点击 New repository 创建新项目. 填入项目基本信息，点击 Create Repository 确认。

create_repository

确认完成后会看到如下页面:

after_create_repository

1.2 为 repository 开启 github page 选项

如图，我们选中 Setting tab

repository_setting_page

往下滚动，找到 Github Pages 选项，将 Source 改为 master branch , 最后点击 Save 按钮
github_page_finish_setting

最后我们会得到一个链接，通过这个链接，待会我们就能通过这个链接访问到该项目的 github pages 页面。

1.3 代码 clone 到本地，并创建几个基本文件

create_sample_files

1.4 添加基础代码

注意这里 html 因为和 css 以及 js 放在同一目录，所以我们用相对路径来引用。

代码逻辑很简单，就是在页面加载好后在页面中添加 Hello, github pages :) 这段文字。

index.html

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <title>Github Page demo</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" type="text/css" media="screen" href="main.css" />
    <script src="index.js"></script>
</head>
<body>
    <div id="main-content">

    </div>
</body>
</html>

index.js

window.onload = function() {
  document.getElementById('main-content').innerHTML = 'Hello, github pages :)'
}

main.css

#main-content {
  font-size: 36px;
  font-weight: bold;
  padding: 16px;
}

1.5 将代码更新到 github 仓库

    cd github-pages-demo
    git add .
    git commit -m "Add simple code"
    git push

1.6 看看效果

现在我们访问之前开启 github pages 选项时获得的 url, 就可以看到效果了

注: 代码 push 上去后，可能要过几分钟才会部署好生效

效果如图 ⬇️

simplest demo

二. 使用前端框架时，如何使用 github pages

如今我们创建一个前端项目的时候，已经很少手动创建 index.html, main.js , main.css 这文件了，通常我们都会选择一个前端框架，并使用相应的 command line tool 来初始化项目。

这里笔者用 Vue 的 webpack 项目做介绍, rect 和 angular 进行类似的配置即可。

创建项目

首先我们用 vue-cli 创建一个 webpack 管理的 vue 项目 ( 点我安装 vue-cli ),

vue init webpack github-page-vue-demo

然后我们进入项目，看看目录结构:

simplest demo

可以看到 config 目录中有三个文件:

config                     //  配置目录
├── dev.env.js             // 用于 development 模式的环境变量
├── index.js               // 用于配置 `dev` 模式和 `prod` 模式的 webpack config 文件
└── prod.env.js            // 用于 product 模式的环境变量

这里我们需要配置的就是 index.js 文件，先看看该文件内容 (这里将不相关的代码用...略过), 其中我们需要关注的是 module.exports 的 build 属性，我们将在这里配置 webpack build 时生成文件的路径

module.exports = {
  dev: {
      ...
  },

  build: {
    // Template for index.html
    index: path.resolve(__dirname, '../dist/index.html'),

    // Paths
    assetsRoot: path.resolve(__dirname, '../dist'),
    assetsSubDirectory: 'static',
    assetsPublicPath: '/',
    ...
  }
}

可以看到图中主要配置了 index 文件和 assets 文件的路径. 默认执行 yarn run build 后 webpack 会将项目打包到项目根目录的 ./dist 文件夹，如图:

default build result

修改编译配置

但是 github pages 默认只能识别项目根目录的 index 文件，如果我们想要让 github pages 识别到我们 build 出来的文件应该怎么办呢?

你可能会想到直接将 dist 文件夹中 build 生成的文件直接复制到项目的根目录，这确实是个办法. 但是这样的话，我们每次 build 完，都需要手动复制一边文件，这无疑增加了很多重复性的工作。

我们可以通过修改默认的配置来达到项目 build 的文件直接生成到项目根目录的目的，像这样:

module.exports = {
  dev: {
      ...
  },

  build: {
    // Template for index.html
    index: path.resolve(__dirname, '../index.html'),  //之前是 '../dist/index.html'

    // Paths
    assetsRoot: path.resolve(__dirname, '../'),  // 之前是 '../dist'
    assetsSubDirectory: 'static',
    assetsPublicPath: './',    // 之前是 '/'
    ...
  }
}

所做的改动就是去掉了默认的 dist 目录，并且将 assets 的引用路径从绝对路径改为了相对路径 .

去掉 dist 目录是为了将 build 的 target 路径改为项目根目录. 改为相对路径是因为在部署到 github pages 的时候，我们的域名是 https://username.github.io/repositoryName , 也就是说我们的项目是部署在子域名上的，如果用绝对路径会导致 assets 文件 404。

这样修改完后我们又发现一个问题: 在这样的配置下, build 结束生成的 index.html 文件会覆盖原有的 template index.html 文件，并且根目录多了一个 static 文件夹，很容易让人对这个文件夹的作用产生疑惑. 有没有更好的解决办法呢？

让我们回到 github page 的 setting 页面:

default build result

可以看到这里有一个选项是 master branch /docs folder . 当前状态是不可选的，原因是我们的项目代码里面没有 /docs 目录。

这个选项的意思是 github page 可以识别我们项目中的 docs 文件夹，并在这个文件夹中寻找 index 文件进行部署. 选中这个选项后，我们只需要将之前 webpack 默认的 dist 文件夹改为 docs 文件夹即可，修改后配置如下:

module.exports = {
  dev: {
      ...
  },

  build: {
    // Template for index.html
    index: path.resolve(__dirname, '../docs/index.html'),  //之前是'../dist/index.html'

    // Paths
    assetsRoot: path.resolve(__dirname, '../docs'),  // 之前是 '../dist'
    assetsSubDirectory: 'static',
    assetsPublicPath: './',    // 之前是 '/'
    ...
  }
}

完成以上的修改后，我们再次运行 yarn run build , 你会发现根目录下多了一个 docs 文件夹，里面承载了 index 文件和 static 文件夹. 我们讲 docs 目录以及其下的文件全部加入 git 版本管理，并 push 到 github。

再次来到该项目的 github page setting 页面，这时 master branch /docs folder 就变成可选中的了. 我们选中这个选项，并保存设置。

过两分钟左右，我们再次访问我们项目的 github page url , 就会发现项目已经部署成功了！

自定义 template

在上一步中，我们自己配置了一个基于 Vue + Webpack 的项目配置. 但如果每次我们想创建一个 demo, 我们都要修改一遍配置的话，还是很花费时间. 特别是忘记了配置步骤的话，还得再查找之前的配置方法。

一个比较好的解决方案是创建一个基础的 template repository, 在下次需要创建一个 demo 项目的时候，直接 fork 过来，基于这个项目着手开发即可。

比如我经常使用的技术栈是: Vue + D3.js + Webpack, 我就给自己创建了一个这样的 template, 并做好 github page 的配置. 下次要做数据可视化 demo 的时候，直接 fork 这个 repository 进行开发，节省了许多项目配置的时间，如果有和我类似技术栈的小伙伴，不妨一试:

Vue + D3.js + Webpack (github page ready)
github 地址