一个 URL 背后的三层机制，以及该把哪个链接写进 README

00摘要 · 八条可证伪的核心论断

只读这一页也能拿走结论；后续每一节都是其中某条论断的展开与举证。

1. 这个 URL 能打开，是域名路由、构建发布、浏览器运行三层机制叠加的结果，三层分别由不同的仓库与脚本负责，互不耦合。
2. 域名层不是本项目配置的：自定义域 wangjunjian.com 归用户站点仓库所有，本仓库 cname=null；项目站点因此被 301 到自定义域子路径，全程零 DNS 改动。
3. 发布层由 .github/workflows/pages.yml 驱动，每次 push 到 main 重建并部署；仓库只提交源码，可玩的单文件产物不入库。
4. 单文件不是「把文件拼起来」那么简单：vite.config.ts 强制单 chunk，scripts/inline.mjs 做防御式内联，两者共同保证线上与 file:// 双击是同一个字节。
5. 浏览器内以固定 60Hz 逻辑步进运行；键盘、触屏、手柄先归约成 8 个 InputRole 并按来源分桶，再进入与设备无关的纯逻辑层。
6. 「一键 236」不是第二套规则：它把 ↓ / ↘ / →+攻击 排成 3 个逻辑帧，复用与键盘手摇完全相同的 detectQcf() 判定链。
7. 保留 github.io 的代价可量化：本机 8 次采样中，跨主机重定向使 num_connects 从 1 变 2，time_redirect 中位数 0.980s。
8. 这不是二选一：自定义域更体面也更快，但链接寿命受制于另一个仓库的 cname 配置；github.io 是 GitHub 官方兜底的永久地址。建议主链接换域名、备链保留。

01三层机制总览

把「打开一个链接」拆到底，会看到三个彼此独立的责任层。分层是理解后面所有实现细节的前提，也是排查线上问题时的定位顺序。

02第一层 · 域名路由：为什么链接落在自己的域名下

这是最反直觉的一层，也是最容易被误认为「改了 DNS」的一层。事实是：本项目一行域名配置都没写。

GitHub Pages 有一条账户级规则：当用户站点仓库（wang-junjian/wang-junjian.github.io）绑定了自定义域，该账户下所有项目站点都会自动挂到这个自定义域的 /<仓库名>/ 路径下，同时从 <username>.github.io/<repo>/ 发出 301。所以只要在 kof-3d 仓库启用 Pages，内容就自动出现在 wangjunjian.com/kof-3d/。

可复核的配置事实

03第二层 · 构建发布：从源码到 783 KB 单文件

发布链路解决「内容从哪来」，构建链路解决「为什么内容可以只有一个文件」。后者是这套方案能同时支持在线试玩与离线双击的关键。

npm run build 展开是三步：tsc --noEmit → vite build → node scripts/inline.mjs。vite.config.ts 用 inlineDynamicImports: true、cssCodeSplit: false、assetsInlineLimit: 100_000_000 和固定 entryFileNames: 'game.js'，把 Three.js 与全部业务代码压成恰好一个 JS chunk 与最多一个 CSS chunk；base: './' 保证产物里不出现绝对路径。

四个决定成败的细节

发布工作流

.github/workflows/pages.yml 在 push 到 main（或手动 workflow_dispatch）时触发两个 job：build 跑 npm ci → test → typecheck → build，再组装 site/——把单文件复制成 index.html 与 kof-3d.html，加 .nojekyll 阻止 Jekyll 处理，用 build.txt 记录 $GITHUB_SHA 供线上溯源；deploy 调官方 deploy-pages@v4。permissions 只授 contents: read / pages: write / id-token: write，concurrency 用 cancel-in-progress: false 避免两次部署互相踩出站点空档。

CI 只跑纯逻辑层，因为 npm run verify 依赖本机 Chrome；浏览器端到端断言留在本地验收。这是有意的能力边界，不是遗漏。

04第三层 · 浏览器运行：固定步进与设备归约

单文件加载后，window.__kof.ready 置位即代表 Three.js 场景、帧表与 HUD 都已就绪。之后所有玩法都跑在一个与设备无关的纯逻辑层上。

src/main.ts:245 的 FixedLoop 把逻辑固定在 60Hz：每个逻辑帧先 controls.sync()（Gamepad 是轮询设备，没有 DOM 事件，必须在采样前汇入），再 match.step(input.sample())；渲染回调按 alpha 插值更新姿态、特效与镜头。因此浏览器帧率波动不会改变判定结果，顿帧（hitstop）冻结逻辑时视觉时间也一起冻结。

三个不显眼但决定手感的设计

• 按来源分桶持有。core/input.ts 用 Map<InputSource, Set<InputRole>> 保存按住状态，roleHeld() 只要任一来源持有即为真。手柄每帧 press/release 才不会误清键盘按住的方向。
• 触屏不卡键。view/Controls.ts 用 setPointerCapture 配合 pointerup / pointercancel / lostpointercapture 三处抬键，手指滑出按钮也不会留下一个永远按着的攻击键。
• 宏指令不另立规则。queueQcf() 排出的三帧依次进出 Match 的 20 帧历史，第三帧触发 detectQcf()；返回的绝对方向由 Fighter 与 facing 比对，输入层完全不掺角色状态。

05可复核的验证：每个结论都有一条命令能复跑

这一节把前面所有断言压成可执行的观测。证据强度按「配置事实 / 实测 / 代码事实 / 推断」标注，实测数据注明样本量与口径。

06两个方案的正面对比

问题收窄成一句话：README 与仓库 homepage 继续写 github.io（方案 A，现状），还是改成 wangjunjian.com/kof-3d/（方案 B）。两者页面内容完全相同，差别只在访客抵达内容之前的那段路。

实测数据

采样区间：A 的 total 最小 2.339s / 最大 4.056s，B 的最小 1.844s / 最大 5.274s。两组分布明显重叠，因此「B 一定更快」这个说法证据不足；能站得住的结论是「B 少一次连接、少一次 TLS、少一段确定的重定向阶段耗时」。

对比矩阵

07判断与落地

先明确标注：以下是观点，不是共识。数据与配置事实在前一节，判断建立在这些事实与你的使用场景之上。

落地清单

• 把 README.md 第 5 行「在线试玩 / Play online」的 URL 改成 https://wangjunjian.com/kof-3d/。
• 执行 gh repo edit wang-junjian/kof-3d --homepage "https://wangjunjian.com/kof-3d/" 更新仓库主页链接。
• 在同一段补一行备用地址：https://wang-junjian.github.io/kof-3d/，注明会自动跳转。
• 中英摘要里若出现「published to GitHub Pages」这类措辞，无需改动——部署方式没有变。

复跑命令

# 1) 量 301 的净开销（8 次采样，比较 num_connects 与 time_redirect）
for i in $(seq 1 8); do
  curl -sSL -o /dev/null -w '%{num_connects} %{time_redirect} %{time_total}\n' \
    https://wang-junjian.github.io/kof-3d/
done

# 2) 直达对照
for i in $(seq 1 8); do
  curl -sS  -o /dev/null -w '%{num_connects} %{time_total}\n' \
    https://wangjunjian.com/kof-3d/
done

# 3) 确认两种入口拿到同一份产物
shasum -a 256 kof-3d.html
curl -sSL https://wang-junjian.github.io/kof-3d/index.html | shasum -a 256
curl -sSL https://wangjunjian.com/kof-3d/build.txt

# 4) 本地两层验收（按 README 固定顺序）
npm test && npm run typecheck && npm run build && npm run verify

仍然存在的差距

竖屏手机目前只给提示、不提供完整竖屏布局；手柄键位写死、无重绑定与振动；AI 不放必杀；无选人界面；M3 的美术打磨与联机未解禁。这些与链接选型无关，列在这里避免把「能打开」误读成「已完工」。