CleanMCA · 白名单文件

白名单代表保留范围

白名单是纯文本文件，每行写一个要保留的文件名。它不是删除列表，也不是目录路径列表。最小示例：

r.0.0.mca
r.0.1.mca
r.1.0.mca
r.-1.-1.mca

Minecraft 的区域文件名通常形如 r.<区域 X>.<区域 Z>.mca。CleanMCA 使用完整文件名做精确匹配，不能写成 r.*.*.mca、region/r.0.0.mca 或一组坐标范围。

文件格式规则

• 每行一个文件名；不要在文件名后追加说明文字。
• 空行会被忽略，建议用空行分组时仍保持文件简单。
• 仓库示例使用以 # 开头的注释行。Python 版本会把非空行读入集合，注释行不会匹配普通 MCA 文件；为了让 Bash 与 Python 的行为更容易对照，建议注释只用于说明，不要让它看起来像文件名。
• 文件名匹配区分大小写。r.0.0.mca 和 R.0.0.MCA 不是同一个字符串。
• 文件应使用 UTF-8 保存，尤其是白名单旁边有中文注释或路径时。
• 同一份白名单会应用到 region、poi 和 entities。通常三个目录中的对应文件名相同，但某些文件可能只存在于其中一个目录。

官方仓库附带的 whitelist_example.txt 可以作为起点，但其中的坐标只是示例，不代表你的世界应该保留这些区域。

维度和路径范围

一次运行只处理 --region 指向目录的三个同级目录。主世界、下界、末地或其他自定义维度必须分别确认对应的 region 路径和白名单；不要因为主世界的列表正确，就直接对另一个维度复用它。

如果你只想缩小某个世界或维度的存档，白名单应只包含该目标目录中需要保留的文件名。把另一个维度的文件名混入列表不会让工具跨目录保留文件，因为工具从不会访问 --region 之外的路径。

从 Dominion 生成列表时要重新审核

CleanMCA 的 README 提到可以使用 Dominion 根据领地生成白名单。这个列表表达的是 Dominion 生成器定义的保留范围，不等同于“玩家最近访问过的所有内容”。运行前请确认：

1. 生成列表时使用的是正确的服务器、世界和维度；
2. 领地边界外仍有需要保留的公共区域、交通线、刷怪场或管理区域时，已经额外加入对应文件；
3. 领地删除、迁移或跨维度数据没有让旧文件名误留或新文件名遗漏；
4. 列表中没有把备份目录、相对路径或通配符当成文件名；
5. 你在测试副本中验证了玩家常用位置、村民 POI、实体密集区域和重要结构。

只依据领地生成列表时，未被列入的未认领区域会被视为可以清理。这个策略可能符合某些服务器的磁盘管理目标，也可能删除仍有价值的公共建筑；最终范围由管理员负责确认。

执行前的人工检查

建议至少用文件管理器或命令行列出目标目录中的文件，抽查白名单中的几个坐标和一个明确不应保留的坐标。Linux/macOS 可以先查看目录内容：

ls -la /srv/minecraft/world/region
sed -n '1,40p' /srv/tools/CleanMCA/whitelist.txt

Windows 可以使用：

Get-ChildItem "D:\Minecraft\world\region"
Get-Content "D:\Tools\CleanMCA\whitelist.txt" -TotalCount 40

不要把“白名单行数”当成“将要保留的有效文件数”。Python 版本会去除空白并用集合去重；Bash 版本只显示文本行数，两者都不会替你证明每一行对应一个现存文件。