> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acondawayuno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/deployment/github-actions) 完成；本页面解释运行时配置和排查边界。

The Living Index builds to a Cloudflare Worker through `vinext`. [GitHub Actions](/deployment/github-actions) owns routine releases; this page explains runtime configuration and troubleshooting boundaries.

## Runtime configuration / 运行时配置

`wrangler.jsonc` defines:

```json theme={null}
{
  "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:

```text theme={null}
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` 加载。

<Warning>
  `.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`.
</Warning>

## Canonical deployment / 标准部署

```bash theme={null}
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.

```bash theme={null}
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](/faq/troubleshooting).

如果部署成功但房间仍像旧版本，请继续阅读 [Troubleshooting](/faq/troubleshooting)。