CleanMCA

这件工具解决什么问题

CleanMCA 是一个面向服务器管理员的命令行清理工具。它读取一份 MCA 文件白名单，然后在指定存档的 region、poi 和 entities 三个目录中，删除名称不在白名单里的普通文件。它不会分析区块内部内容，也不会判断文件是否“看起来可以删除”；白名单就是最终保留范围。

工具仓库同时提供 Bash 脚本、Python 版本和 Windows 批处理入口。对于生产服，建议优先使用 Python 版本：它跨平台、支持 UTF-8 路径和文件名，并且会在删除前真正等待 y、yes 或 是 确认。

开始前必须知道

• 这是删除工具，不是压缩工具，也没有回收站、撤销或内置恢复功能。
• 运行前必须停止服务器，并备份整个世界；至少要能恢复 region、poi 和 entities，更推荐备份整个世界目录。
• --region / -r 参数必须指向某个维度的 region 目录，而不是世界根目录。工具会从它的上一级寻找同级的 poi 和 entities。
• 同一份白名单会同时作用于三个目录。一个文件名只要不在白名单中，就可能在对应目录被删除；工具不会只删除扩展名为 .mca 的文件。
• 当前 master 分支的 Bash 版本虽然显示确认提示，但读取结果后没有分支判断；输入 n 也可能继续执行。因此生产操作应优先使用 Python 版本，并把 Bash 当作已确认路径后的兼容入口。

推荐阅读顺序

你要做的事	从这里开始
第一次部署工具	安装与运行环境
编写或检查保留列表	白名单文件
执行一次清理并验证结果	实际使用
在 Windows、Linux、macOS 或 WSL 上运行	平台与入口差异
规划备份、停服和回滚	安全边界与恢复
运行失败或清理后出现异常	故障排查

资料基准

本文档按 CleanMCA 仓库 master 分支现有的 CleanMCA.sh、CleanMCA.py、CleanMCA.bat、README_python.md 和 whitelist_example.txt 撰写；仓库最近一次提交记录为 2025-07-17。脚本可能继续变化，实际运行时应优先查看当前仓库文件、终端输出和备份状态。