第 8 章发布第一个 Walrus Site

Walrus Sites 把静态网站发布成一个 Sui 对象：HTML、CSS、JavaScript、图片等文件存储在 Walrus，站点对象在 Sui 上保存资源索引和所有权。浏览器不会直接访问 Walrus 节点，而是通过 portal 把普通 HTTP 请求解析为 Sui 查询和 Walrus 读取。

本章目标是发布一个最小静态站点，并学会用同一条命令更新它。

准备工作

本书以 2026-05-06 核对到的稳定版本为准：Walrus Mainnet / Testnet release 均为 v1.47.1，Devnet v1.48.0 是预发布版本。除非你明确在测试预发布功能，本章建议使用 testnet-v1.47.1 或 mainnet-v1.47.1 对应的工具链。

你需要已经完成：

sui client active-env
sui client active-address
walrus --version
site-builder --help

Testnet 发布还需要测试网 SUI 和 WAL。Mainnet 发布需要真实资产，并且通过 https://wal.app 访问 Mainnet 站点时需要 SuiNS 名称，第 10 章会展开。

最小站点目录

本仓库提供一个可直接部署的例子：

examples/sites/minimal-static-site/
├── assets/
│   └── site.css
├── about.html
├── index.html
└── ws-resources.json

Walrus Site 的入口文件必须是站点根目录下的 index.html。先本地预览：

cd examples/sites/minimal-static-site
python3 -m http.server 8080

浏览器打开 http://127.0.0.1:8080。这个本地服务器只用于预览；发布到 Walrus Sites 后不需要源站服务器。

第一次部署

从仓库根目录运行：

site-builder --context testnet deploy --epochs 1 examples/sites/minimal-static-site

deploy 会做两件事：

把目录中的静态资源打包上传到 Walrus。
在 Sui 上创建一个 Walrus Site 对象，保存每个路径到 Walrus 资源的索引。

第一次部署成功后，site-builder 会把新建站点对象 ID 写回 examples/sites/minimal-static-site/ws-resources.json 的 object_id 字段。这个文件应该提交到代码库，因为后续部署要靠它判断“更新已有站点”，而不是“创建新站点”。

如果你不想污染示例文件，可以先复制一份：

cp -R examples/sites/minimal-static-site /tmp/my-walrus-site
site-builder --context testnet deploy --epochs 1 /tmp/my-walrus-site

查看部署结果

部署输出会列出资源路径和站点对象 ID。常用检查命令：

site-builder sitemap --id 0xYOUR_SITE_OBJECT_ID
site-builder convert 0xYOUR_SITE_OBJECT_ID

sitemap 查看站点对象里登记了哪些资源。convert 把十六进制对象 ID 转成 Base36，用于部分 portal 的子域名解析。

访问方式取决于网络和 portal：

网络	访问方式
Testnet	使用本地或自托管 portal。官方文档当前不提供公共 Testnet portal。
Mainnet	使用 `https://wal.app`，但需要先把 SuiNS 名称指向 Walrus Site 对象。
自托管 portal	可使用 Base36 对象 ID 或把 portal 固定到某个站点。

更新站点

修改 index.html 或 assets/site.css 后，再运行同一条命令：

site-builder --context testnet deploy --epochs 1 examples/sites/minimal-static-site

只要 ws-resources.json 中已有 object_id，deploy 就会更新对应站点。签名钱包必须是该 Walrus Site 对象的 owner，否则交易会失败。

如果你要显式更新另一个站点：

site-builder --context testnet deploy \
  --object-id 0xYOUR_SITE_OBJECT_ID \
  --epochs 1 \
  examples/sites/minimal-static-site

不要部署源码根目录

对 Vite、Next.js 静态导出、Astro、Docusaurus、mdBook 等项目，site-builder 的目录参数应该指向构建产物，而不是项目根目录：

npm run build
site-builder --context testnet deploy --epochs 3 dist

错误示例：

site-builder --context testnet deploy --epochs 3 .

这样会把 node_modules、源码、临时文件甚至密钥误上传，增加费用，也扩大泄露风险。生产项目应在构建输出目录中保留 index.html、静态资源和 ws-resources.json，只发布浏览器真正需要的文件。

Keyboard shortcuts

Walrus 从入门到精通