打包文档_如何免费从 0 构建快速文档网站

背景图片使用了John Schnobrich 拍的照片

这一篇文章聊一聊如何做一个文档网站，免费并且加载速度较快，是我在做 http://usetable-ahooks.js.org/ 的一些经验，可以多多交流。

做文档网站，主要分成四部分来讲，分别是

• 选择文档构建器，我们选择了 dumi
• 选择静态文件托管服务器，我们选择了 surge
• 选择域名，我们选择使用了 js.org
• 选择 CDN，我们选择用了 http://unpkg.zhimg.com/

文档构建器

dumi 拥有完善的构建能力，从开发阶段到打包阶段。我们只需要按照它的规范写文档，基本上可以自动完成一个漂亮的本地文档网站。

dumi 的配置 publicPath 支持我们配置 CDN 路径，这个方便我们下面把一些静态文件换成 CDN 路径。

静态文件托管

surge 使用起来也是比较方便的，第一步你下载 surge 包

npm install surge -g

然后在你当前目录执行 surge

surge ./dist --domain <your-domain-name>.surge.sh

dist 是 dumi 默认打包生成的文件夹，并且可以自定义 domain 名称，比如我这边就叫做 usetable-ahooks.surge.sh ，推上去之后你就会发现你可以通过 usetable-ahooks.surge.sh 访问到你的文档了。

但是这个时候路由还是有问题，当你直接访问你的网站多级目录的时候就出现找不到对应页面，因为这个时候路由不是你的 js 来控制而是 surge.sh 来控制，而 dumi 默认打包之后是一个 SPA，路由只能用本地的 js 来控制。不过这个问题 surge 提出了一个解法，Adding a 200 page for client-side routing。

所以我在构建成功之后写了一个脚本，把 dumi 生成的 index.html copy 一份到 200.html，与 index.html 同一级。代码也是很简单，可以看这里。

const fse = require('fs-extra'); 
fse.copySync('./dist/index.html', './dist/200.html');

这个时候路由都是 umi 来控制了。不过你可能想要换个装逼点的域名，比如 http://xxx.js.org，好像是比 xxx.surge.sh 更有前端味道。

域名

你可以到 js.org Github 仓库上提 PR，他们处理效率很快，基本上如果符合他们的规范的话基本上一天就可以搞定。详情可以参考我之前配置的 usetable-ahooks.js.org PR。

CDN

其实上面已经完成了一个免费网站的建立了，但是你会发现访问你的网站还是很慢，基本上有时候想要 30 秒才能出来页面，首屏实在太久了。

分析的原因是打包出来的 umi.js 压缩之后有 700 K，加载速度太慢，影响了页面渲染速度。毕竟我们直接把静态文件放在 surge 上面了，国内访问速度还是比较慢。

所以转换了另外一个思路，就是 surge 只是托管 html，其它静态资源比如 js、css、svg 托管在一些 CDN 平台上。第一个想到的是 unpkg.com，直接同步 npm 包到 CDN 上，然后搜了一把居然有国内镜像，unpkg.zhimg.com，基本上 700 K 的 js 可以在 400 毫秒内返回，这个真的太棒了。

因为 http://unpkg.zhing.com 是直接去同步 npm 包的，所以我把 dist 文件夹里面的内容写了一个脚本同步到 npm，npm 包的版本都是时间戳，这样子每次推上去都是最新的包，然后结合刚才说的 dumi 配置 publicPath，把 html 内嵌的静态文件全部设置到 CDN 上，具体的代码可以查看 useTable/scripts 。

最后

最后把刚才要处理的事情写成一个命令，结合 package.json 的 script，可以做到一键更新文档。

{
  "scripts": {
    // 以时间戳作为版本，发布 dist 目录内容到 npm 上
    "cdn": "node ./scripts/cdn",
    // copy index.html 到 200.html，解决路由问题
    "surge": "node ./scripts/surge",
    // 生成时间戳的版本号，这个版本号跟上面发布 npm 的版本号一致，并且构建文档
    "docs:build": "node ./scripts/version && dumi build && npm run cdn && npm run surge",
    // 发布到 surge
    "docs:pub": "surge ./dist --domain usetable-ahooks.js.org; surge ./dist --domain usetable-ahooks.surge.sh",
    // 入口
    "docs:deploy": "npm run docs:build && npm run docs:pub",
  }
}

使用的时候就直接 npm run docs:deploy 就行了。据不完全统计，之前 30 秒的速度，有了国内 CDN 能力加持之后，速度可以提升到 3 秒以内，如果第二次访问的话，加上 HTTP 一些强缓存之后基本可以在 1 秒内打开页面。

最后是网站长的样子

更多信息可看

• 官网 https://usetable-ahooks.js.org/
• Github https://github.com/ahooksjs/useTable/