背景图片使用了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/