walrus-sites

Walrus Sites — 去中心化网站托管

**MCP 工具：**如果你的环境支持，请同时查询 Sui 文档 MCP 服务（https://sui.mcp.kapa.ai），以获取最新答案。用它来核实信息，以及查询这些参考文件未涵盖的详细信息。

Walrus Sites 可将静态网站（HTML/CSS/JS）部署到 Walrus，并通过链上 Sui 对象追踪网站资源。门户服务会解析网站子域名，从 Walrus 获取资源，并通过 HTTP 提供服务。最终得到的是完全去中心化的前端——无需中心化服务、CDN 或 DNS。

**来源限制：**本技能中的所有信息均来自 MystenLabs/walrus-sites 仓库和 Walrus Sites 文档。扩展或更新此技能时，只能使用这些来源。请勿使用第三方博客或非官方教程。

常见故障：

1. **Blob 过期。**发布时设置的 epoch 数量过少，网站会悄然失效——Blob 过期后，门户会返回 404。请始终设置较大的 --epochs 值（30+）。
2. **门户配置错误。**门户的 original_package_id 必须与 Walrus Sites 框架包（site::Site）匹配，而不是你的应用 Move 包。测试网示例配置中已包含正确值——不要更改。
3. **测试网网站无法使用 wal.app。**公共 wal.app 门户仅提供主网网站服务。测试网需要自托管的本地门户。
4. **SPA 路由。**单页应用需要 ws-resources.json 路由配置来处理客户端路由。没有该配置时，直接访问 /my-route 会返回 404。

---

子技能

publishing — 构建和部署网站

路径： publishing/SKILL.md **适用情形：**部署新网站、更新现有网站、选择 epoch 时长、配置 ws-resources.json 或排查 site-builder 错误。 涵盖内容：site-builder publish、site-builder update、--epochs 标志、Blob 过期、ws-resources.json 配置、SPA 路由、网站命名、用于调试的 site-builder sitemap、site-builder destroy。

portal — 运行测试网本地门户

路径： portal/SKILL.md **适用情形：**用户需要查看测试网网站、设置本地门户、修复门户 404，或了解门户解析的工作方式。 **涵盖内容：**克隆门户、安装依赖项（Bun）、portal-config.yaml、original_package_id 注意事项、启动服务、URL 格式、端口冲突、主网与测试网的区别。

---

路由指南

任务	加载
将前端部署到 Walrus Sites	publishing/
更新已部署的网站	publishing/
修复 404 或过期网站	publishing/ + portal/
在本地查看测试网网站	portal/
设置本地门户	portal/
门户显示“找不到页面”	portal/ + publishing/（检查 Blob 是否过期）
配置 SPA 路由	publishing/
查看网站拥有哪些资源	publishing/（site-builder sitemap）
删除已部署的网站	publishing/
在 Walrus Sites 和传统托管之间进行选择	下方的技能内容

---

技能内容

核心概念

• 站点对象。 类型为 site::Site 的 Sui 对象（来自 Walrus Sites 框架包）。它保存元数据（名称、描述）以及将资源路径映射到 Walrus Blob 引用的动态字段。通过 site-builder publish 创建，归发布者地址所有。

• 资源。 部署目录中的每个文件都会成为存储在 Walrus 上的资源。较小的文件可能会合并到一个“quilt” Blob 中。每个资源都有一个路径（例如，/index.html、/assets/main.js）和可选的 HTTP 标头。

• Portal。 一种服务器，可将 <base36-site-id>.localhost:3000 URL 映射到链上站点对象。它会读取站点的动态字段以查找请求的资源路径，从 Walrus 聚合器获取 Blob，并将其作为 HTTP 响应返回。Portal 是框架级基础设施，不属于你的应用。

• ws-resources.json。 位于站点根目录中的配置文件，用于控制资源标头、路由和站点元数据。首次发布时会自动生成，并包含站点对象 ID。之后运行时，site-builder 会读取此文件，以确定是创建新站点还是更新现有站点。

• Blob 过期。 Walrus Blob 的存储期限有限，以 epoch 计量。Blob 过期后，Portal 将无法再获取它们，并会返回 404。使用 site-builder sitemap <object-id> 检查过期日期。使用更高的 --epochs 值重新发布即可解决。

规则

1. 在测试网部署时，始终使用 --epochs 30 或更高值。 较低的值（例如 5）会导致 Blob 在几天内过期。对于主网生产环境，请使用更高的值或 --permanent。
2. 发布前先构建。 运行 npm run build（或等效命令）生成静态 dist/ 目录。site-builder 会发布你指定目录中的内容。
3. 除非确定 Walrus Sites 框架包已升级，否则不要更改 Portal 配置中的 original_package_id。 测试网示例值是正确的。
4. wal.app 仅支持主网。 对于测试网，请从 MystenLabs/walrus-sites 仓库自行托管 Portal。
5. 首次发布后检查 ws-resources.json。 它会记录站点对象 ID。请将其保留在版本控制中，以便后续发布更新现有站点，而不是创建新站点。

常见错误

• 使用 --epochs 5 发布，然后纳闷为什么一周后站点就消失了。 Blob 已过期。请使用 --epochs 30+ 重新发布。
• 将 Portal 的 original_package_id 改为你的应用包 ID。 Portal 需要的是 Walrus Sites 框架包 ID（site::Site），而不是你的 Move 合约包 ID。这两者完全不同。
• 尝试通过 wal.app 访问测试网站点。 它只提供主网服务。测试网需要本地 Portal。
• 忘记在发布前构建前端。 site-builder publish dist/ 会发布 dist/ 目录中的内容。如果你没有先运行 npm run build，发布的就是源文件或过期的构建产物。
• 部署 SPA 却没有配置回退路由。 React/Vue/Svelte SPA 使用客户端路由。直接访问 /borrows 会请求 Portal 查找 /borrows 资源，但该资源并不存在。请在 ws-resources.json 中配置回退路由。
• 启动 Portal 前没有关闭 3000 端口。 Vite 开发服务器、Next.js 或其他工具通常会使用 3000 端口。如果该端口已被占用，Portal 会静默地绑定失败。