第 9 章站点配置、路由与元数据

ws-resources.json 是 Walrus Sites 的部署配置文件。site-builder 在部署时读取它，但它本身不会作为网站资源公开给访客。这个文件同时承担两个角色：记录已有站点的 object_id，以及声明 headers、routes、redirects、metadata、ignore 等发布规则。

一个完整但仍然可读的配置如下：

{
  "object_id": "0xYOUR_SITE_OBJECT_ID",
  "headers": {
    "/index.html": {
      "cache-control": "no-cache",
      "content-type": "text/html; charset=utf-8"
    },
    "/assets/site.css": {
      "cache-control": "public, max-age=31536000, immutable"
    }
  },
  "routes": {
    "/app/*": "/index.html",
    "/*": "/index.html"
  },
  "redirects": {
    "/old-about": {
      "location": "/about.html",
      "status_code": 301
    },
    "/docs": {
      "location": "https://docs.wal.app",
      "status_code": 302
    }
  },
  "metadata": {
    "site_name": "Walrus Starter",
    "description": "A minimal static site deployed with Walrus Sites.",
    "link": "https://YOUR_SUINS_NAME.wal.app"
  },
  "ignore": [
    ".DS_Store",
    "*.map",
    "README.md"
  ]
}

object_id

第一次 deploy 没有 object_id 时会创建新站点；成功后 site-builder 会把对象 ID 写入 ws-resources.json。后续部署读取这个 ID 并更新同一个站点。

如果你维护 staging 和 production，建议分开构建目录或分开资源文件：

dist-testnet/ws-resources.json
dist-mainnet/ws-resources.json

不要让测试网部署覆盖主网站的 object_id。

headers

headers 为资源配置 HTTP 响应头。注意：header 规则按资源精确路径匹配，不支持 * 通配符。配置里的 header 名称建议统一小写，尤其是 content-type。构建工具生成带 hash 的文件后，应在发布脚本中为每个产物写入一条精确路径规则。

{
  "headers": {
    "/index.html": {
      "cache-control": "no-cache",
      "content-type": "text/html; charset=utf-8"
    },
    "/assets/app.3f1a2c.js": {
      "cache-control": "public, max-age=31536000, immutable",
      "content-type": "application/javascript; charset=utf-8"
    },
    "/assets/app.a91c04.css": {
      "cache-control": "public, max-age=31536000, immutable",
      "content-type": "text/css; charset=utf-8"
    }
  }
}

入口 HTML 不应长期强缓存，因为它通常引用最新构建产物。带 hash 的 JS、CSS、图片可以长缓存；下一次构建换文件名即可让浏览器获取新版本。

routes 与客户端路由

routes 是站点内部路由映射。它不会执行服务端代码，只是告诉 portal：当某个 URL 路径没有同名资源时，应该返回哪个已有资源。

单页应用最常用的配置：

{
  "routes": {
    "/*": "/index.html"
  }
}

这样用户直接打开 /dashboard/settings 时，portal 返回 /index.html，再由 React Router、Vue Router、SvelteKit 静态前端等客户端路由接管。

多入口站点可以写更具体的规则：

{
  "routes": {
    "/admin/*": "/admin.html",
    "/docs/*": "/docs.html",
    "/*": "/index.html"
  }
}

注意两点：

路由目标必须是已经存在于站点对象中的资源，例如 /index.html。
通配符只能表达路径前缀匹配，复杂动态逻辑应放到前端应用里处理。

redirects

redirects 返回 HTTP 3xx。它适合迁移旧链接或跳转到外部文档：

{
  "redirects": {
    "/v1": {
      "location": "/docs/getting-started.html",
      "status_code": 301
    },
    "/github": {
      "location": "https://github.com/MystenLabs/walrus-sites",
      "status_code": 302
    },
    "/legacy/**/*": {
      "location": "/index.html",
      "status_code": 308
    }
  }
}

常用状态码：

状态码	用途
`301`	永久迁移，搜索引擎和浏览器可能长期缓存。
`302`	临时跳转，适合活动页或未定稿迁移。
`308`	永久迁移并保留请求方法。静态站点里常用于严格替换。

如果只是为了 SPA 能刷新任意路径，优先用 routes，不要用 redirects。routes 保持浏览器地址不变；redirects 会改变地址栏。

metadata

metadata 写入站点对象，钱包和浏览器工具可以用它展示站点信息：

{
  "metadata": {
    "site_name": "Walrus Starter",
    "description": "A minimal static site deployed with Walrus Sites.",
    "link": "https://walrusstarter.wal.app"
  }
}

建议生产站点至少填写：

字段	建议
`site_name`	用户看到的正式名称。
`description`	一句话说明站点用途。
`link`	最终公开访问地址，优先填 SuiNS 或自定义域名。

ignore

ignore 防止无关文件进入站点：

{
  "ignore": [
    ".DS_Store",
    "*.map",
    "*.log",
    "README.md",
    "node_modules/**/*"
  ]
}

即使配置了 ignore，也应从构建产物目录部署，而不是从源码目录部署。ignore 是最后一道防线，不是发布流程的主隔离机制。

验证配置

部署前至少做三项检查：

test -f dist/index.html
test -f dist/ws-resources.json
site-builder --context testnet deploy --epochs 1 dist

部署后查看资源索引：

site-builder sitemap --id 0xYOUR_SITE_OBJECT_ID

如果 routes 指向不存在的资源，部署交易会失败。优先在 CI 中让构建产物固定、可检查，再交给 site-builder deploy。

Keyboard shortcuts

Walrus 从入门到精通