如何使用 SteamTools 的 manifest 与 Lua 文件

分步说明：搜索 Steam App ID、生成 manifest + Lua ZIP、安装 SteamTools，以及常见错误与处理方式。

最近更新: 2026-07-15

本页说明 steamtools.games 上的生成器：输入游戏名或 App ID，下载 ZIP（Lua + key.vdf + README），再配合 SteamTools 桌面客户端使用。网站本身无需注册，但在文件真正生效前，你仍需要先安装 SteamTools。

1. 你输入游戏名

首页的输入框会对你按键做 250 ms 的去抖，然后请求我们自己的 /api/search 接口。该接口是 Steam 公开 store 搜索的代理，返回前 5 条匹配结果，每条带上 App ID、显示名、一个小尺寸的 capsule 图。

没有本地索引，每次搜索都是到 Steam 的实时往返。我们不会把搜索结果缓存进数据库，因为 Steam 整个目录太大、缓存命中率太低，缓存的过期数据反而比不缓存更糟。

如果你已经知道 App ID —— 而且你应该知道，因为找 App ID 对任何 Steam 游戏都是 30 秒的事 —— 直接把它粘进输入框即可。生成器会识别 4–10 位的数字、关掉下拉，让你跳到第 3 步。

2. 你选择一条结果

点击下拉里的某一条，会在内部设置两个状态值：App ID（整数）和游戏名。输入框更新为显示名，"Generate" 按钮变为可用。

下拉是键盘可达的：方向键移动高亮、Enter 选中、Esc 关闭。第一条结果默认高亮，所以快速按 Enter 就直接选中第一条。

如果搜索返回零结果，下拉会显示"无匹配"提示，并附 App ID 查找器和 FAQ "我的游戏不在搜索结果里" 两条链接。

3. generate 请求

点击 Generate 会发出 POST /api/generate，带上 App ID（以及可选的 branch 名，用于 Steam 的 beta 分支）。该接口会：

校验 App ID 是合法范围（1 到 2,147,483,647）的正整数。
调 Steam 的 appdetails 接口确认游戏真实存在，并取回规范名与 capsule 图。这是 generate 流程中我们唯一一次触碰 Steam API 的地方。
从 Steam 的 appinfo 接口读目标分支下的 depot 列表，给每个 depot 选最新的公开 build，并解析出对应的 depot 解密密钥。
用这些值把 manifest 文本和 Lua 脚本文本渲染出来。
把两个文件以 text/plain 内联返回，让浏览器按正确的文件名保存，整个过程服务端不存任何状态。

整个往返在热路径上通常耗时 200–400 ms，在冷路径（Cloudflare 缓存驱逐后的首次请求）上最多 1.2 s。如果你看到超过 3 s 的情况，瓶颈在 Steam 的 appdetails 接口，不在我们这边。

4. 你下载 ZIP 并放置文件

结果卡片提供 Download ZIP（推荐），以及可选的 Lua / key.vdf 直链。ZIP 文件名形如 appmanifest_<APPID>_public.zip，内含：

<APPID>_public.lua
key.vdf
简短说明 README.txt

自动化场景也可以直接请求 /api/files/<APPID>/zip。

放置：若尚未安装，先安装 SteamTools，再把 .lua 与 key.vdf 复制到 SteamTools 安装根目录（与可执行文件同一文件夹）并完全重启 SteamTools。完整的图文步骤与排错见 /install 安装页。

本生成器不提供经典的 appmanifest_*.acf。若你走 depotcache/scripts 的 .acf 流程，见 manifest 文件说明。

网站不会在你电脑上运行安装器，也不分发游戏本体——只有你主动下载的小文本文件。

四步走怎么串起来

┌────────────┐  debounce   ┌────────────┐  proxy       ┌──────────────┐
│ 输入框      │ ──────────► │ /api/search│ ───────────► │ Steam store  │
└────────────┘   250ms     └────────────┘              │  search API  │
                                                          └──────────────┘
       │ 选中结果（AppID + 名称）
       ▼
┌────────────┐  POST       ┌────────────┐  渲染         ┌──────────────┐
│ Generate   │ ──────────► │/api/generate│ ───────────► │ .acf + .lua  │
│  按钮       │             │  （服务端） │              │  text/plain  │
└────────────┘             └────────────┘              └──────────────┘
       │ 用户点击下载
       ▼
   ┌─────────┐    ┌────────────────┐
   │depotcache│   │ SteamTools/    │
   │ /manifest│   │ scripts/lua    │
   └─────────┘    └────────────────┘
       │ 重启 SteamTools
       ▼
    游戏解锁

浏览器里跑什么

首页是 TanStack Start 服务端渲染应用。Hydration 之后与产品相关的脚本包括：

去抖搜索输入。
生成 / 下载结果卡片。
从 localStorage 读「最近」横栏。

若后台开启了分析或广告，可能还会加载可选的第三方脚本——详见隐私政策。搜索与生成不依赖这些脚本。

服务端跑什么

Nitro 服务，承载路由并打包 paraglide 消息模块。
两个 API 路由，都在 src/routes/api/ 下。
/api/generate 每个 IP 1.5 s 限速，/api/search 每个 IP 300 ms 限速。
边缘节点的请求日志，仅用于防滥用。每 14 天滚动清理。

五种错误与每种的修法

这是生成器唯一会返回的错误。看到任意一种，根因都在 Steam 那边，不在我们这边。

1. "App not found"（`/api/generate` 返回 HTTP 404）

Steam 的 appdetails 接口返回 success: false。最常见的原因是 Steam 已经下架（delisted）的 app 还装在你机器上。Steam 对部分下架 app 仍保留 appdetails 可达，对另一部分则彻底关闭。我们这边没办法绕过 —— 这种情况请看 manifest-files 页面"下架 app"那节。

第二常见的原因是 App ID 拼写错了。App ID 是整数："Portal 2" 是 620，不是 620 （带尾部空格）也不是 0620（带前导零）。重新粘贴，去掉所有空白。

2. "Branch not found"

你填了一个目标 app 上不存在的分支名。Steam 分支名区分大小写、必须完全匹配：public、beta、beta_1、ptb、experimental。把字段留空，得到 public 分支。

要查某个 app 有哪些分支，去 SteamDB 的 branches 页 —— 那是分支名和对应 buildid 的权威来源。

3. "Rate limit exceeded"

你在最近 1.5 s 内发起了超过一次的 /api/generate 请求，或最近 300 ms 内发起了超过三次 /api/search 请求。等一下再试。限速是自动的、按 IP 生效的、自动恢复的，没有"解封"按钮。

如果你真的有高频需求（构建服务器、自动化流水线），走公开 API 并自己加退避循环。用多 IP 绕过限速是永久封禁的依据。

4. "Steam appdetails timeout"

Steam 的 appdetails 接口在 5 s 内没有返回。这种情况几千次请求出现一次。生成器会返回 503 并带 Retry-After: 2 头。再点一次 Generate 就行 —— 第二次基本都成功，因为 Steam 边缘缓存热了。

5. "Empty manifest file"

manifest 下载成功了但是 0 字节，或者只有 AppState 头没有字段。这说明该 app 没有公开的 depot —— app 存在于 Steam 目录里但还没有 build 发布。常见于"即将推出"状态的 app、限定封闭测试的 app、以及一些发行商工具。

我们这边没办法修。发行商一旦推送公开 build，生成器对那个 App ID 就会开始返回非空 manifest。

SteamTools.games vs Watt Toolkit vs GreenLuma vs SteamDB

知道每个工具做什么很重要，因为这四个在 Steam 解锁的讨论里经常同时出现。

工具	是什么	做什么	什么时候用
SteamTools.games（本站）	Web 端 manifest + Lua 生成器	生成 SteamTools 需要的两个文件，不动你的 Steam 安装	当你想要某个 app 的 manifest + Lua，又不想装任何东西
Watt Toolkit（前 Steam++）	包含 SteamTools fork 的 Steam 工具套件	本地运行，提供网络加速、成就解锁、SteamTools 桌面端解锁	当你想要完整的本地 Steam 模组套件，不只是一次性 manifest
SteamTools（桌面客户端）	Steam depot-key 缓存与 Lua 运行环境	从 `depotcache` 和 `scripts/` 读 manifest + Lua，Steam 启动时执行	当你拿到那两个文件想真正去解锁 app
GreenLuma	另一套用不同机理的 Steam 解锁器	直接 patch Steam 让它接受任意 depot	当你需要非 SteamTools 兼容的解锁（少见）
SteamDB	只读的 Steam 元数据追踪站	展示一个 app 的 `buildid`、depot 列表、分支	当你需要查分支名或确认最新 build

这四个工具不是竞品 —— 它们覆盖同一套工作流的不同层。SteamTools.games 把活交给 SteamTools（桌面客户端），而大家平时说"SteamTools"指的就是那个桌面客户端。

性能与限制

站点托管在 Cloudflare 边缘网络。缓存驱逐后的首次请求是冷启动（约 600–1200 ms）；同 App ID 的后续请求是热路径（约 150–300 ms）。
/api/generate 每 IP 每 1.5 s 限一次请求，/api/search 每 IP 每 300 ms 限一次。限速是有意为之、不可协商的，因为 Steam 的 appdetails 自己也限速。
生成器不支持超过 100 个 depot 的 app。真实场景下我们没见过超过 30 个 depot 的。如果你遇到了，把 App ID 报给我们。
生成器不支持超过 2,147,483,647（int32 上限）的 App ID。我们解析过的最高 App ID 在 400 万出头；Steam 自己也分不到更高。

服务不会做什么

不会修改你电脑上的任何游戏文件。
不会绕过 Steam 的 DRM、授权或登录校验。
不会把搜索历史存到服务端。首页的"最近"横栏读的是你浏览器的 localStorage，不是我们的。
不会要你注册账号、邮箱或手机号。
不会捆绑或再分发任何游戏内容。生成的两个文件都是小文本（manifest < 4 KB，Lua < 1 KB）。

如果你想验证服务确实按它说的方式工作，整个服务端代码在开源项目的 src/routes/api/ 和 src/server.ts。客户端在 src/blocks/generator.tsx。每条代码路径只有一两个文件；没有任何东西藏在不可读的构建步骤里。

进一步阅读

安装 SteamTools —— Windows / macOS / Linux 桌面客户端
manifest 文件详解 —— 文件里到底有什么
如何找 Steam App ID —— 当你不知道 App ID
常见问题 —— 更长更深的问答列表
生成器错误排查 —— 错误表的博客版
开发者 / API —— 自动化与脚本化使用

另见

什么是 Steam manifest 文件，怎么配合 SteamTools 使用？ —— 完整的前门指南；本页是其中一个部分的深入展开。