静态客户端工具怎么选托管:资源、路由与运行边界
用可复现的 JavaScript 与 WASM 示例,核对静态资源、深链接、项目子路径和后端边界,再按官方能力与使用条件比较托管方案。

给一个浏览器里的小工具选托管,先问清楚每次使用时发生什么。用户打开页面,下载 HTML、JavaScript 和 WASM,再在浏览器里算出结果,这条路径可以交给静态托管。用户关闭页面后还要继续跑任务,或者服务需要保管密钥、核验付费权限、同步多人的数据,就要另列服务端需求。
我用一个很小的加法页把边界拆开:输入 19 和 23,点击 Add locally,得到 42。它有首页、可直接打开的 /sum/、一个自制的 41 字节 WASM 文件,以及真实的 404 页面。文中的运行结果来自下载包解压后的本机浏览器验证;Cloudflare Pages 和 GitHub Pages 的比较来自官方文档核对,未向这两个服务部署示例。
先画出输入、计算与输出的位置
“静态”描述的是交付文件的方式。托管服务通过 HTTP 把页面和资源发给浏览器,页面随后执行 JavaScript 或 WASM。浏览器可以读取用户选中的文件、处理数据、生成 Blob 并导出;这些动作本身不要求服务端执行业务计算。是否适合客户端,还要看算法、浏览器 API、内存和设备性能。
把你要做的事情写成一句话,例如:“用户选一张图片,浏览器调整尺寸,再把新文件下载到自己的设备。”这句话已经给出了输入、计算和输出。如果下一句变成“明天自动发给团队,并跨设备保留历史”,就增加了持续运行、身份与共享存储需求。
| 任务 | 运行位置与要求 |
|---|---|
| 本地读取文件、计算、下载结果 | 可考虑纯客户端;核对库是否能在浏览器运行 |
| 刷新后保留本机设置 | 可用浏览器存储;跨设备同步另行设计 |
| 调用公开的外部数据接口 | 页面可静态托管;仍依赖对方接口、网络和 CORS |
| 保管付费 API 密钥、核验权限 | 需要受信任的服务端或独立身份服务 |
| 支付回调、共享数据库、关闭页面后的任务 | 需要对应后端能力与运维方案 |
编译时用过 Node.js、Python 或 CI,不意味着公开页面也要运行这些进程。先检查构建输出:若输出已经是完整的 HTML、脚本和资源,就可以由静态服务交付。反过来,把 API 密钥打包进 JavaScript 或 WASM,访问者仍能拿到这些字节,不能用编译格式承担保密职责。
一个能拆开检查的最小例子
下载示例 ZIP。包内源码为本次自制,使用 MIT 许可证,没有第三方依赖。add.wat 保留了 WASM 的可读来源;add.wasm 是同一函数的 41 字节编码。
static-hosting-check/
index.html
sum/index.html
404.html
app.js
add.wasm
.nojekyll
add.wat
serve.py
README.md
LICENSE
前六项是静态站点文件。.nojekyll 用于 GitHub Pages 从分支发布普通静态文件时跳过 Jekyll;其他项目若使用构建发布,沿用自己的发布方式。serve.py 只是本机教学服务器,不是要上传并运行的生产后端。示例没有安装步骤,解压后进入 static-hosting-check 目录,使用 Python 3.9 或更新版本运行:
python3 serve.py --port 8760
打开 http://127.0.0.1:8760/,等页面显示 Ready 后点击 Add locally。保留默认输入会显示 42;改为 -10 和 3 会显示 -7。输入范围限制在正负一百万的整数,避免把 WASM 的 32 位整数加法误当成任意精度运算。打开 http://127.0.0.1:8760/sum/ 并刷新,应继续加载同一套脚本与 WASM。最后打开 /missing/,应收到 HTTP 404。

实际浏览器结果:WASM 从 /demo/add.wasm 加载,输入与结果在页面内计算。
这个例子让 WASM 参与计算,是为了核对资源交付条件;加法本来就可以由 JavaScript 完成,这里没有性能优势的结论。单线程小文件也没有覆盖媒体处理库的大内存、多线程或大资源需求。
深链接需要服务端找到正确的入口
在页面里点击链接成功,只说明当前导航成功。把 URL 复制到新窗口、直接打开或刷新时,浏览器会重新向托管服务请求这个路径。
示例把 /sum/ 做成实际的 sum/index.html,因此服务只需按路径找到文件。它和首页使用同一份 app.js;第二个 HTML 是为了明确路由交接,没有客户端路由器。对于页面数量少的工具,预先生成几个 HTML 常常就够用。
SPA 则常用一份 HTML,在 JavaScript 中解释 /sum/ 等路径。静态服务器必须知道哪些请求要交回入口文件,客户端路由器再决定显示什么。Cloudflare Pages 的 Serving Pages 文档明确说明:没有顶层 404.html 时,Pages 假定项目是 SPA,把路径交给根入口;存在顶层 404.html 时,按其 Not Found 规则查找最近的 404 页面。本示例刻意带有顶层 404.html,选择真实文件和真实 404 的交付方式。
GitHub Pages 的自定义 404 文档说明了 404.html 或 404.md 的做法。为这个两页示例准备真实 HTML,便于直接打开与刷新。若项目改用 hash 路由,例如 /#/sum,# 后面的内容不会作为 HTTP 路径发送,服务仍只拿到首页请求,但链接形式也随之变化。把 SPA 壳塞进 404 页面可以让浏览器显示应用,收到的错误状态仍需单独核对。
为了看到兜底过宽的问题,另开一个终端:
python3 serve.py --port 8762 --spa-fallback
访问 /missing/ 会拿到首页和 HTTP 200;访问 /missing.wasm 也会拿到首页的 HTML。这是教学服务器故意制造的错误配置,不是对任何供应商实际响应的测量。测试未知页面和缺失资源时,同时看状态码、Content-Type 与响应内容,能发现“看起来请求成功,实际拿错文件”的故障。
子路径会改变资源地址
GitHub Pages 官方介绍区分两种默认地址:用户或组织站在 https://<owner>.github.io/,项目站在 https://<owner>.github.io/<repositoryname>/。自定义域名也受支持;实际挂载位置以最终公开 URL 为准。
若项目站位于 /demo/,写 fetch('/add.wasm') 会请求域名根目录的 /add.wasm,丢掉项目目录。示例让资源相对于脚本解析:
const wasmURL = new URL('./add.wasm', import.meta.url);
const response = await fetch(wasmURL);
首页以 ./app.js 加载脚本,sum/index.html 以 ../app.js 加载脚本。两种页面最终都找到项目根的脚本,WASM 地址也跟着脚本的位置确定。对带打包器的项目,要把构建工具的 base 或 public path 设置为实际挂载目录,并核对图片、字体、Worker 和动态 import,不能只改首页链接。
在第三个终端验证子路径:
python3 serve.py --port 8761 --base /demo/
直接打开 http://127.0.0.1:8761/demo/sum/,页面应显示从 /demo/add.wasm 加载,默认计算仍为 42。同一服务器上的 /add.wasm 应返回 404。这个本机测试检查 URL 解析,未模拟 GitHub 的完整路由、缓存或部署系统。
WASM 加载成功要核对字节和 MIME
MDN 对 instantiateStreaming 的说明要求服务以 application/wasm 返回 WASM;错误 MIME 会使 Promise 以 TypeError 拒绝。示例先检查状态与类型,再交给浏览器编译:
if (!response.ok) throw new Error(`WASM HTTP ${response.status}`);
if (response.headers.get('Content-Type')?.split(';')[0].trim()
!== 'application/wasm') {
throw new Error('Expected application/wasm');
}
const { instance } = await WebAssembly.instantiateStreaming(response);
在正常模式中,/add.wasm 实际返回 200 application/wasm 和 41 字节模块。错误兜底中的 /missing.wasm 返回 200 text/html,浏览器的流式编译实际抛出 MIME TypeError。只检查 response.ok 会漏掉这种假 200。改用 arrayBuffer() 再编译可以采用另一种加载方式,却不会让 HTML 变成有效的 WASM;诊断时仍应看服务为什么返回了错误内容。
同源意味着页面和资源使用相同的协议、主机和端口,这个例子无需跨域读取 WASM。若把资源挪到另一域名,要核对对方的 CORS。若换成依赖 SharedArrayBuffer 的多线程库,还要核对跨源隔离及相应响应头,并在目标浏览器验证;本例不需要这些条件,不能据它的成功推断所有 WASM 工具都能运行。
两种托管方案按需求对照
以下能力和使用规则在 2026 年 10 月 5 日核对官方原文。这里只比较本例需要的交付条件,不估算账单或按价格排名。
这里的 Cloudflare Pages 指该产品。Trylog 自身使用 Workers Static Assets,并在根路径执行语言选择;那是本站的路由需求,纯静态工具不会因此普遍需要一段业务 Worker。
| 核对项 | Cloudflare Pages | GitHub Pages |
|---|---|---|
| 静态页面 | 匹配 HTML 路径交付 | 从仓库交付 HTML、CSS、JS |
| 深链接方案 | 真实文件;也有条件性的默认 SPA 入口 | 本例使用真实文件;可提供自定义 404 |
| 挂载路径 | 按最终站点 URL 检查 | 用户站根路径;默认项目站有仓库前缀 |
| 服务端扩展 | Pages Functions 是独立服务端代码能力 | Pages 定位为静态站点托管 |
Cloudflare Pages 的 _headers 文档提供静态资源响应头的配置方式;这些规则不应用到 Pages Functions 生成的响应,后者要在代码里处理。对于需要自定义静态响应头的项目,这是一项可核对的能力。是否引入 Functions,要由认证、接口等实际需求决定,纯客户端计算不用为了“能运行 JavaScript”就增加它。
资源体积也会改变选择。Pages 的 Limits 文档列出单个站点资源上限为 25 MiB,Free 计划文件数上限为 20,000。一个浏览器媒体库即使不用服务端计算,也可能因单个 WASM 或模型文件过大而无法按原样上传。不要用这个 41 字节样本推断你的资源能通过;先统计真实构建产物,再考虑拆分或别的资源交付方案。换域名或服务后,也要重新检查同源、CORS 与隐私约定。
GitHub Pages 的使用限制对选择更直接:官方说明它不允许作为免费托管来经营在线业务、电商,或主要用于促成商业交易、提供商业 SaaS 的网站。计划做收费工具时,先核对实际用途是否符合规则,不能因为页面能静态构建就直接选择它。同一文档还列出已发布站点不得超过 1 GB、每月 100 GB 的软带宽限制等条件;“软限制”不能当成保证容量或服务等级。
据这些文档,对本例这种少量静态页面,主要工程取舍是文件路径和 404;若强调仓库项目展示,就核对 GitHub Pages 的使用范围与项目路径。若需要 Pages 已明示的静态响应头或 SPA 默认行为,可以继续核对 Cloudflare Pages 的适配性。正式决定仍要把用途、真实资源大小、上线方式和当前服务条款一起写入需求表。
用一张需求表完成交接
把下面的“本例”列替换为你的项目事实,就能交给另一位开发者核对,也能在换托管时重复使用。
| 项目 | 本例的要求与通过条件 |
|---|---|
| 输入与输出 | 两个有界整数 → 本地 WASM 加法 → 页面结果 |
| 数据位置 | 输入和结果留在页面;加载代码仍发 HTTP 请求 |
| 运行能力 | 支持 JS 模块与 WASM 流式实例化;单线程 |
| 公开文件 | 两个 HTML 入口、404、JS、41 字节 WASM |
| 公开路径 | / 或 /demo/;资源跟随脚本位置解析 |
| 页面路由 | /sum/ 直接打开和刷新成功;未知路径 404 |
| 资源响应 | WASM 为 200、application/wasm、有效模块 |
| 失败显示 | 资源加载失败显示 Load failed,不输出伪结果 |
| 后端需求 | 本例无服务端业务计算、账户或共享存储 |
| 使用条件 | 核对平台条款、文件和部署限制;保留来源 |
发布验收时,用最终域名重新做这些检查。浏览器 Network 中应能找到 HTML、脚本、WASM 等静态请求;本例输入两组数并计算后,资源请求列表没有新增计算请求。真实工具还要核对 fetch、XHR、表单、WebSocket、分析脚本等出站通道。GitHub 的官方介绍也明确记录访客 IP 用于安全,所以“用户文件本地处理”要准确说明数据处理范围,不能扩成“访问没有任何网络元数据”。
交接包里保留构建文件、可读源码、许可证、路由要求和可复现命令。全部验证结束后用 Ctrl-C 停止自己启动的服务器。下一次换托管时,沿同一张需求表核对新的实际响应,计算逻辑与文件交付条件就有清楚的分界。 要把这些检查接入构建与发布,可接着读静态工具的构建、发布与恢复检查。