Cloudflare Worker Runtime Reference

Understand the Worker, static asset binding, model delivery, configuration, and post-deployment checks behind the GitHub Actions release path.

The Living Index 通过 vinext 构建为 Cloudflare Worker。日常发布由 GitHub Actions 完成；本页面解释运行时配置和排查边界。

The Living Index builds to a Cloudflare Worker through vinext. GitHub Actions owns routine releases; this page explains runtime configuration and troubleshooting boundaries.

Runtime configuration / 运行时配置

wrangler.jsonc defines:

{
  "name": "the-living-index",
  "compatibility_date": "2026-07-24",
  "compatibility_flags": ["nodejs_compat"],
  "main": "./worker/index.ts",
  "assets": {
    "directory": "dist/client",
    "not_found_handling": "none",
    "binding": "ASSETS"
  },
  "images": {
    "binding": "IMAGES"
  }
}

Setting	Role
main	Worker entry for SSR and image optimization
ASSETS	Serves hashed client bundles and files copied from public/
IMAGES	Supports vinext image transformation
nodejs_compat	Provides the Node compatibility required by the server bundle

Build output and public assets / 构建产物与公开资源

npm run build produces dist/. Files under public/ become same-origin static assets, including:

public/content/site-content.json
public/uploads/profile/*
public/uploads/photography/*
public/uploads/cards/*
public/uploads/models/*

The application bundle imports app/generated/scene-config.ts. At runtime it fetches JSON for editorial content and uses the generated snapshot for the published scene. Custom GLBs load from their same-origin /uploads/models/<uuid>.glb paths.

应用 bundle 会导入 app/generated/scene-config.ts。运行时从 JSON 读取编辑内容，并使用生成快照作为发布场景；自定义 GLB 从同源 /uploads/models/<uuid>.glb 加载。

.content-studio-cache/models 是本地暂存目录，不属于 Worker 静态资源，也不应提交。只有点击 Save to project 后仍被引用的 GLB 才进入 public/uploads/models。

.content-studio-cache/models is a local staging directory. It is neither a Worker asset nor a committed directory. Only GLBs still referenced at Save to project enter public/uploads/models.

Canonical deployment / 标准部署

npm run typecheck
npm run lint
npm test
git diff --check
git push origin main

The GitHub workflow runs npm run deploy with repository secrets after the quality job succeeds.

质量 Job 成功后，GitHub workflow 使用仓库 Secrets 运行 npm run deploy。

Manual deployment / 手工部署

本机直接部署只用于首次 Cloudflare 配置或受控诊断，不属于普通内容与功能更新流程。它需要本机 Cloudflare 凭证，并会绕过 GitHub 的审查记录。

A local direct deployment is only for initial Cloudflare setup or controlled diagnosis. It is not the normal content or feature workflow. It requires local Cloudflare credentials and bypasses the GitHub review record.

npm run deploy

Do not run it merely to make an uncommitted Studio draft visible. Save, validate, commit, and push instead.

不要为了让未提交的 Studio 草稿上线而直接部署。应先保存、验证、提交并推送。

Caching / 缓存

• Hashed JS and CSS bundles can use long-lived caching. / 带 hash 的 JS/CSS 可以长缓存。
• HTML should update quickly after deployment. / HTML 应在部署后快速更新。
• UUID model paths are content-address-like in practice; replacement creates a new file path. / UUID 模型路径在实际使用中近似内容寻址；替换会产生新路径。
• site-content.json is fetched with cache: "no-store" by the client. / 客户端以 cache: "no-store" 请求内容 JSON。
• A browser draft is not a Cloudflare cache. Normal routes ignore it; ?studio=1 may restore it locally. / 浏览器草稿不是 Cloudflare 缓存；普通路由忽略它，?studio=1 才可能恢复。

Post-deployment checks / 部署后检查

• Confirm the latest GitHub Actions run completed successfully. / 确认最新 Actions 运行成功。
• Open a normal route without ?studio=1 and compare it with committed content. / 用不含 ?studio=1 的普通路由核对已提交内容。
• Test Chinese and English. / 测试中英文。
• Open an enabled built-in and an interactive custom asset. / 打开一个启用的内置物件和一个交互自定义资产。
• Verify GLBs return 200 from /uploads/models/.... / 确认 GLB URL 返回 200。
• Test a deep link and browser Back behavior. / 测试深链接与浏览器返回。
• Use a private window when ruling out browser-specific state. / 排除浏览器本地状态时使用无痕窗口。

If the deployment succeeded but the room still looks old, continue with Troubleshooting.

如果部署成功但房间仍像旧版本，请继续阅读 Troubleshooting。