Windows 包管理器 Scoop：从底层原理、命令行到提交自己的软件包

current 为什么重要#

每个版本各住一个目录，current 则是指向当前版本的目录联接。更新时，Scoop 可以先把新版本放进新目录，再把 current 改指过去。旧版本不会立刻消失，因此我们还能切换版本或在确认无误后清理它。

这有点像铁路道岔：程序版本是不同轨道，current 只负责把入口切到当前轨道。切换版本不需要搬动整列火车。

1
# 查看一个软件当前实际目录
2
scoop prefix git
3

4
# 重新建立 current、Shim 和快捷方式
5
scoop reset git

Shim 为什么不等于把所有目录塞进 PATH#

传统做法常常给每个软件追加一条 PATH。安装 $N$ 个软件，环境变量里就可能多出 $N$ 个目录。Scoop 通常只需要把一个固定的 shims 目录加入 PATH，再由里面的入口转发到 apps\<app>\current 下的真实程序。

Manifest 中的 bin 决定创建哪些 Shim：

1
"bin": "uuu.exe"

它也能给程序换一个更适合敲命令的别名：

1
"bin": [
2
    [
3
        "Axolotl Launcher.exe",
4
        "axolotl-launcher"
5
    ]
6
]

所以升级后真实路径变了，命令名通常不变。scoop which <command> 可以沿着 Shim 找到它来自哪个软件：

1
scoop which git
2
scoop which axolotl-launcher

Persist 怎样让配置跨版本存活#

如果配置文件跟程序一起留在版本目录，清理旧版本时配置也会被删掉。Manifest 的 persist 会把这些文件或目录转移到 persist\<app>，再用目录联接或硬链接接回程序目录。

1
"persist": "data"

于是程序仍然以为自己在读 apps\<app>\current\data，实际数据却住在版本目录之外。普通卸载默认保留这些数据，彻底删除时才加 --purge：

1
scoop uninstall <app>
2
scoop uninstall <app> --purge

Bucket 为什么本质上是供应链边界#

一个 Bucket 就是一个包含 JSON Manifest 的 Git 仓库。scoop bucket add 会把它克隆到本地，scoop update 再通过 Git 拉取变化。

这也意味着添加第三方 Bucket 不是一个纯粹的搜索操作，而是在增加新的软件供应源。Manifest 可以包含 pre_install、installer 和 post_install PowerShell 脚本。哈希能证明下载内容与 Manifest 期望的一致，却不能证明发布者或 Bucket 本身值得信任。密码学很认真，但它不会替我做价值判断，多少有点遗憾。

安装前我会看一眼 Manifest：

1
scoop info extras/vscode
2
scoop cat extras/vscode
3
scoop home extras/vscode

如果同名软件存在于多个 Bucket，我会显式写成 bucket/app，而不是让搜索顺序替我决定：

1
scoop install main/aria2
2
scoop install games/axolotl-launcher

在安装前修改目录#

默认用户目录是 %USERPROFILE%\scoop，全局目录是 %ProgramData%\scoop。如果我想把用户级软件放到 D:\Scoop，会在安装前设置 SCOOP：

1
[Environment]::SetEnvironmentVariable("SCOOP", "D:\Scoop", "User")
2
$env:SCOOP = "D:\Scoop"
3
irm get.scoop.sh | iex

全局目录由 SCOOP_GLOBAL 控制。写入 Machine 级环境变量和安装全局软件都需要管理员权限：

1
[Environment]::SetEnvironmentVariable("SCOOP_GLOBAL", "D:\ScoopGlobal", "Machine")

我会使用纯英文、无空格的短路径。这不是为了某种神秘仪式，而是为了避开历史安装脚本对空格、编码和引号处理不一致的问题。

已安装后的迁移#

已经安装后再搬目录，比安装前指定路径更容易遗漏状态。基本步骤是：

1. 关闭正在运行的 Scoop 软件。
2. 把整个 Scoop 根目录移动到新位置。
3. 更新 SCOOP 和 PATH 中的 shims 路径。
4. 打开新终端，重建全部链接。

1
scoop reset *
2
scoop checkup

发现软件#

1
# 搜索名称和命令
2
scoop search ripgrep
3
scoop search rg
4

5
# 查看来源、版本、依赖等信息
6
scoop info main/ripgrep
7
scoop depends main/ripgrep
8

9
# 阅读安装清单和打开项目主页
10
scoop cat main/ripgrep
11
scoop home main/ripgrep

搜索不到时，先到 Scoop Directory 搜索社区 Bucket。仍然没有，再考虑自己写 Manifest，不要随手下载一个来历不明的 setup.exe 然后给它管理员权限。

安装、卸载与全局安装#

1
# 安装一个或多个软件
2
scoop install git aria2
3
scoop install extras/vscode
4

5
# 指定架构
6
scoop install main/7zip --arch 64bit
7

8
# 卸载，但保留 persist 数据
9
scoop uninstall vscode
10

11
# 连同 persist 数据彻底删除
12
scoop uninstall vscode --purge

只有确实需要所有用户共享时，我才使用全局安装：

1
# 在管理员 PowerShell 中执行
2
scoop install git --global
3
scoop update git --global
4
scoop uninstall git --global

--skip-hash-check 会跳过完整性校验。除非我正在调试自己刚写的 Manifest，否则不会使用它，更不会把它当作下载失败的通用修复。

更新、锁定、回退与清理#

1
# 更新 Scoop 本体和本地 Bucket
2
scoop update
3

4
# 查看哪些软件可以更新
5
scoop status
6

7
# 更新一个软件或全部软件
8
scoop update git
9
scoop update *
10

11
# 暂停和恢复某个软件的更新
12
scoop hold git
13
scoop unhold git

如果 Manifest 带有 autoupdate，Scoop 还能根据当前清单生成指定旧版本的 Manifest：

1
scoop install gh@2.7.0

这不是对任意软件、任意历史版本都有效。下载地址模式变过、旧文件被上游删除、旧哈希无法取得时，生成仍会失败。

版本切换或 Shim 冲突时使用 reset：

1
scoop reset python
2
scoop reset python@3.12.10

确认新版本工作正常后再清理旧目录和下载缓存：

1
scoop cleanup *
2
scoop cache show
3
scoop cache rm *

cleanup 删除旧的安装版本，cache rm 删除下载包，两者不是同一件事。磁盘空间凭空消失时，我通常两个地方都看。

导出和恢复环境#

1
scoop export > scoopfile.json
2
scoop import scoopfile.json

当前的 export 会记录应用和 Bucket，也可以按命令帮助提供的选项导出配置。我仍然会单独备份重要的 persist 数据，因为软件列表不是数据备份，正如购物清单不是冰箱。

Aria2 要不要装#

Scoop 检测到 Aria2 后会使用它进行多连接下载：

1
scoop install aria2

我不再默认推荐把连接数一口气调到 16。单文件限速、代理、CDN 策略和网络质量不同，多连接不一定更快，反而可能触发限流。遇到异常时先关闭它做对照：

1
scoop config aria2-enabled false

确认确实受益，再按自己的网络配置 aria2-split 和 aria2-max-connection-per-server。

先研究发布物，不要先写 JSON#

我写 Manifest 前会回答这几个问题：

1. 上游有没有稳定、可预测、无需登录的直链？
2. 发布物是单个 EXE、ZIP、7z、MSI，还是必须运行的安装器？
3. 压缩包解开后，真正的程序在哪一层目录？
4. 软件把配置、存档和缓存写到哪里？哪些应该 persist？
5. 版本能否从 GitHub Releases、网页、JSON API 或文件名稳定提取？
6. 下个版本发布时，URL 能否只替换 $version 就得到？

这里最常见的错误是围着当前版本硬编码，最后得到一个只能安装一次的 JSON。好的 Manifest 描述的不是一个文件，而是一族版本。

哈希是安装契约的一部分#

Scoop 默认使用 SHA256。PowerShell 可以直接计算：

1
Invoke-WebRequest $url -OutFile .\download.zip
2
(Get-FileHash .\download.zip -Algorithm SHA256).Hash.ToLower()

SHA256 是 256 bit，通常写成 64 个十六进制字符。只要上游悄悄替换了同一 URL 下的文件，哈希检查就会失败。这既可能是供应链风险，也可能只是上游重新打包，但两种情况都值得停下来调查，而不是条件反射地跳过校验。

常用字段怎样协作#

• architecture：分别描述 64bit、32bit 和 arm64 发布物。
• url / hash：下载地址与对应校验值，多个 URL 就要有同样数量的哈希。
• extract_dir / extract_to：控制从压缩包中取哪一层、放到哪里。
• bin：创建命令行 Shim，也可以定义别名和固定参数。
• shortcuts：创建开始菜单快捷方式，适合 GUI 软件。
• persist：把配置或用户数据移出版本目录。
• depends：必须安装的运行时依赖。
• suggest：可选增强，不强制安装。
• pre_install / post_install：安装前后的 PowerShell 逻辑，能不用就不用。
• installer / uninstaller：必须运行传统安装器时使用。
• checkver：找出上游最新版本。
• autoupdate：用最新版本号重建 URL 等字段。

公共 Bucket 偏爱简单、可预测、便携的安装。十几行自定义 PowerShell 也许能把任何东西按进 Scoop，但维护者还要在六个月后理解它。能用字段表达，就不要写脚本。

让软件自动跟随新版本#

GitHub Releases 是最省事的一种情况：

1
"checkver": {
2
    "github": "https://github.com/example/tool"
3
},
4
"autoupdate": {
5
    "architecture": {
6
        "64bit": {
7
            "url": "https://github.com/example/tool/releases/download/v$version/tool-$version-windows-x64.zip"
8
        }
9
    }
10
}

checkver 负责回答 “最新版本是什么”，autoupdate 负责回答 “知道版本号后，下载地址长什么样”。Scoop 的自动更新工具会替换版本、生成新 URL、下载新文件并计算哈希。

在 Bucket 仓库根目录可以这样检查：

1
$checkver = "$(scoop prefix scoop)\bin\checkver.ps1"
2
& $checkver tool .\bucket
3
& $checkver tool .\bucket -Update

然后安装生成后的本地 Manifest，不能只看 JSON 长得顺眼：

1
scoop install .\bucket\tool.json
2
scoop which tool
3
scoop uninstall tool

GUI 软件还要真的启动、创建配置、升级一次、卸载一次，再检查快捷方式和 persist。安装成功只证明安装流程没有立刻摔倒，标准不算太高。

1. 选对仓库并先提 Issue#

先根据软件类型选择 main、extras、games 或其他专用 Bucket，搜索是否已有同名软件和相关 Issue。贡献规范要求新软件先创建 Issue，说明实现方式和加入理由，等待维护者确认后再写 PR。

main 的要求最严格。一个 GUI 软件即使 Manifest 完美，也不应该硬塞进 main。我的两个例子正好展示了这个分流：mfgtools 去 main，Axolotl Launcher 去 games。

2. Fork、建分支、添加 JSON#

1
git clone https://github.com/<your-name>/Main.git
2
Set-Location Main
3
git switch -c add-tool
4

5
# 把清单放进 bucket 目录
6
git add .\bucket\tool.json
7
git commit -m "tool: Add version 1.0.0"
8
git push -u origin add-tool

字段顺序也有约定，大致从元数据、依赖、架构和安装步骤，走到入口、持久化、版本检测与自动更新。直接参考 BucketTemplate，比发明自己的排列方式省下 review 往返。

公共 Bucket 还要求：

• 使用 4 个空格缩进。
• license 尽量使用有效的 SPDX Identifier。
• 优先提供便携配置和 persist。
• 纯 CLI 软件不创建 shortcuts。
• 不接受命令行参数的纯 GUI 软件通常不需要 bin。
• 数组只有一个元素时尽量改成字符串。
• 只有 32 bit 下载时可以省略 architecture，其他情况应明确架构。

3. 做一次完整生命周期测试#

我至少会验证：

1
# JSON 能否解析
2
Get-Content .\bucket\tool.json -Raw | ConvertFrom-Json | Out-Null
3

4
# 本地清单能否完成安装和运行
5
scoop install .\bucket\tool.json
6
scoop which tool
7
tool --version
8

9
# checkver 能否找到同一版本，autoupdate 能否生成清单
10
$checkver = "$(scoop prefix scoop)\bin\checkver.ps1"
11
& $checkver tool .\bucket
12
& $checkver tool .\bucket -Update
13

14
# 卸载后入口是否消失
15
scoop uninstall tool
16
Get-Command tool -ErrorAction SilentlyContinue

GUI 软件不能用 --version 就算了。我会实际启动它，检查快捷方式，写入一份配置，执行升级，再确认配置仍在。然后普通卸载一次、--purge 卸载一次，分别观察持久数据是否保留和删除。

4. 发 PR，让自动验证器工作#

新 Manifest 的 PR 标题格式是：

1
<app name>: Add version <version>

提交 PR 后，再评论：

1
/verify

这会启动自动 Manifest verifier。CI 通过不代表 review 一定结束，维护者仍可能要求简化脚本、修正许可证、调整 Bucket、补充 persist，或证明 URL 足够稳定。我会把这些反馈理解成未来维护成本的预演，而不是 JSON 格式考试。

5. 合并之后，自动更新才刚开始值班#

只要 checkver 和 autoupdate 正确，Bucket 的自动化就能发现上游新版本、替换 URL、重新计算哈希并提交更新。我的两个 Manifest 都已经进入这条流水线。

这也是我现在判断一个 Manifest 是否完成的标准：不是 “今天能装”，而是 “下个版本发布后，我大概率不用半夜爬起来改 3 个数字”。