部署
把检测网站、本文档和同源代理部署到 Cloudflare Pages，或以纯静态方式发布到 GitHub Pages。
bun run build 同时构建检测网站和本文档：网站输出到 web/dist/，文档预渲染后复制到 web/dist/docs/。一次静态部署在 / 提供检测网站，在 /docs 提供文档。检测网站使用 HashRouter，不需要页面路由重写。
连接方式选择本站代理（或自动模式不能直连）时，请求由同源 /api/proxy 转发；选择自建 Worker 时由你的 Worker 转发。三个同源入口都导入单文件 Worker worker/main.js 中的 proxyRequest：
| 文件 | 运行环境 |
|---|---|
worker/main.js | 代理实现，也可以单独部署为 Cloudflare Worker |
functions/api/proxy.ts | Cloudflare Pages Function |
api/proxy.ts | Vercel Function |
web/scripts/vite-proxy.ts | Vite 开发与预览服务器 |
Cloudflare Pages
创建项目
Pages 项目使用仓库根目录作为根目录，通过 Git 集成部署：
| 设置 | 值 |
|---|---|
| 生产分支 | main |
| 构建命令 | bun run build |
| 输出目录 | web/dist |
| 环境变量 | BUN_VERSION=1.4.2 |
functions/api/proxy.ts 提供同源代理；wrangler.jsonc 固定兼容日期并启用 enable_request_signal，让客户端取消能传到上游。
检查路由与缓存
web/public/_routes.json 只让 /api/proxy 进入 Pages Function。首页、哈希路由、文档页面、JS/CSS、字体、数据清单和 zstd 分段都由 Pages 静态服务直接返回。/api/proxy 的响应标记为 no-store。
不要开启 Cache Everything
不要为整个自定义域添加 Cache Everything 规则，否则可能缓存 API 响应或阻碍部署更新。Pages 自带 CDN 和 Tiered Cache。哈希命名的 JS/CSS 与数据分段（/assets/*、/data/chunks/*、/docs/assets/*）按 web/public/_headers 在浏览器缓存一年并标记 immutable；index.html 与数据清单沿用 Pages 的重新验证策略。长期缓存依赖 web/public/404.html：有这个文件时，Pages 对不存在的文件返回 404；没有它时，Pages 会返回 index.html 和状态 200，部署切换期间这份 HTML 会被当作脚本缓存一年，页面白屏。（2026-10-01 曾因缺少 404.html 白屏，清除 Cloudflare 缓存并更换资源哈希后恢复。）不要删除 404.html。
绑定自定义域
先在 Pages 项目中绑定 lm.ikale.io，再确认 Cloudflare DNS 指向该项目的 *.pages.dev 主机名。只有 Pages URL 的静态资源、/api/proxy 的 JSON/SSE 转发和自定义域都通过后，才能停止旧站点的自动部署。
自定义域 lm.ikale.io 的 /api/proxy 由下文的代理 Worker 路由处理。Pages Function 只服务 *.pages.dev 和预览部署。
代理 Worker 路由
wrangler.proxy.jsonc 把 api/proxy.ts 部署为 Worker lm-fingerpoint-proxy，并绑定路由 lm.ikale.io/api/proxy。Worker 路由先于 Pages 执行，所以该路径不会进入 Pages Function。
不在自定义域上使用 Pages Function 的原因：自定义域把 Pages 当作源站。Cloudflare 会把源站返回的 502 替换成自己的错误页，客户端因此收不到上游的错误信息。另外，自定义域等待源站响应头最多 100 秒，超时返回 524。Worker 路由由 Worker 直接生成响应，不经过这一层源站代理。
修改 worker/main.js 后，除了推送 Pages，还要在仓库根目录运行 bun run deploy:proxy。API 令牌需要账户级 Workers Scripts 编辑权限和 ikale.io 区域的 Workers Routes 编辑权限。
用 Wrangler 发布
bun run build:pages
bun run preview:pages # http://127.0.0.1:8788
bun run deploy:pages若创建的是直接上传项目，也可以运行 bun run build:pages:upload，再把生成的 web/dist/ 上传到 Pages。这个命令会把已编译的函数放入 _worker.js；只上传 bun run build 生成的纯静态目录会丢失同源代理。直接上传项目需要在控制台设置与 wrangler.jsonc 一致的兼容日期和 enable_request_signal。
静态数据
参考库、派生库与二进制检测器在构建时分别用 zstd 19 级压缩，再按 4 MiB 切分到 web/dist/data/chunks/。data/manifest.json 的每一项包含 parts 和 bytes；bytes 是压缩后大小，用于显示下载进度。浏览器按清单拼接、解压；检测只加载需要的数据。参考库加载完成后，网站在后台下载检测器，并在顶栏显示进度；评分开始时若下载未完成，计算行和检测按钮会提示正在等待检测器下载。参考库与检测器不匹配时，构建失败。最大的静态文件小于 Pages 的 25 MiB 限制。CLI 包仍从构建时生成的脱敏派生库和 shared_detector.bin 打包，不依赖压缩后的站点数据。
GitHub Pages
.github/workflows/pages.yml 在推送时构建并保存静态产物，手动触发时发布到 GitHub Pages。手动发布前需要在仓库设置中启用 GitHub Actions 作为 Pages 来源。项目站点位于 /<仓库名>/ 之下，工作流会把 DOCS_BASE 设为 /<仓库名>/docs，文档的链接、搜索索引和 llms.txt 都随之使用这个前缀。
GitHub Pages 没有服务器函数，也就没有本站代理 /api/proxy：连接方式为“自动”或“本站代理”时，需要代理的请求会失败。允许浏览器跨域的接口可以在 API 配置的“连接方式”中选“直连”使用 API 模式（含分词器探测）；其他接口选自建 Worker，Worker 的 ALLOWED_ORIGINS 需要包含 Pages 站点的 origin。
Vercel
vercel.json 用 bun run build 构建，输出 web/dist，api/proxy.ts 作为同源代理，最长运行 300 秒并支持取消。
文档站
文档位于 docs/，是 React Router 的 SPA，所有页面在构建时预渲染：
- 每页的 HTML 与数据文件；
- 每页的 Markdown 版本
/docs/llms.mdx/<页面>/content.md（英文为/docs/en/llms.mdx/<页面>/content.md），供“复制 Markdown”和 LLM 工具使用； - 每页的 Open Graph 图片
/docs/og/<页面>/image.png（英文为/docs/en/og/<页面>/image.png）； - 检测网站首页的 Open Graph 图片
/docs/og/detector.png，检测网站的index.html把它用作og:image和twitter:image； - 静态搜索索引
api/search，以及llms.txt与llms-full.txt。
DOCS_BASE 决定文档的路径前缀，默认 /docs；上面的路径都以它开头。SITE_ORIGIN 是文档和检测网站的公开来源，默认 https://lm.ikale.io，用于两者的 Open Graph 标签和 Markdown 版本里的绝对网址；部署到其他域名（Vercel、Pages 预览或分支站点）时设为该域名的来源。本地开发用 bun run dev:docs，单独构建用 bun run --cwd docs build。
最后更新于