packwiz 使用教程：用 Git 友好的 TOML 格式打造可自动更新的 Minecraft 整合包

packwiz 使用教程：用 Git 友好的 TOML 格式打造可自动更新的 Minecraft 整合包

【免费下载链接】packwizA command line tool for editing and distributing Minecraft modpacks, using a git-friendly TOML format. Supports CurseForge and Modrinth mods with automated updates!项目地址: https://gitcode.com/gh_mirrors/pa/packwiz

如果你维护过 Minecraft 整合包，八成经历过这样的崩溃瞬间：给朋友传了十几个 JAR 文件，对方启动时缺一个依赖；或者为了把模组版本从 1.20.1 升到 1.21，得手动逐个核对文件。packwiz 正是为了解决这类痛点而生的命令行工具——它不直接管理 JAR，而是把每个模组写成一段轻量的 TOML 元数据，配合 Git 做版本控制，并且天然支持 CurseForge 与 Modrinth 两大模组平台的自动更新。

一、为什么需要 packwiz：它到底解决了什么问题

传统整合包的做法是把模组 JAR 直接塞进 mods 文件夹，然后打包压缩发出去。听起来简单，实际维护时全是坑：

• 版本混乱：谁改了哪个模组、改到什么版本，完全靠记忆；
• 协作困难：多人共同维护时，文件冲突几乎无法避免；
• 更新繁琐：平台出新版本后要重新下载、替换、再分发。

packwiz 的思路是"元数据驱动"：每个模组对应一个.pw.toml文件，里面记录文件名、下载地址、哈希值和更新来源。真正的 JAR 文件只在需要时才被拉取下来，而元数据本身全是纯文本，可以放进 Git 仓库里像管理代码一样管理。

简单来说：你管理的是"模组清单"，而不是"模组文件"。这彻底解决了以上三个痛点，也让整合包体积从几百 MB 缩到几十 KB。

二、packwiz 的安装步骤与首次运行

packwiz 是纯命令行工具，安装方式很灵活，二选一即可。

方式一：直接下载预编译版本

从项目的 CI 构建产物里挑对应你系统的压缩包，解压后把可执行文件放进系统 PATH 路径（Windows 用户在"环境变量"里配置，Linux/macOS 用户放到/usr/local/bin），然后在终端输入packwiz --help验证是否生效。

方式二：Go 一键编译安装

如果你装了 Go（1.19 或更新版本），一条命令就能完成：

go install github.com/packwiz/packwiz@latest

首次编译要拉取依赖，耐心等一会儿就好。

安装完成后，找一个空目录作为整合包项目根目录，运行初始化命令：

packwiz init

这时它会像向导一样问你整合包名称、作者、版本号、Minecraft 版本和模组加载器（Fabric、Forge、Quilt 等）。回答完所有提问，目录里会出现两个核心文件：

• pack.toml：整合包主清单，记录包信息和 Minecraft 版本；
• index.toml：文件索引，登记所有已加入的模组元数据。

到这里，一个"骨架整合包"就建好了，接下来就可以往里加模组了。

三、packwiz 核心使用场景实战

场景一：从 Modrinth 批量添加模组

这是最常用的操作。packwiz modrinth add命令接受模组的 slug（网页地址里那一串短名称）、完整 URL，甚至直接支持模糊搜索：

packwiz modrinth add sodium

如果匹配到多个结果，它会弹出交互菜单让你选择具体项目；选中后，packwiz 会自动匹配与你整合包兼容的版本，并递归解析必选依赖（比如安装钠的同时会自动带上前置库）。命令结束后，mods/目录下会多出一个sodium.pw.toml。

CurseForge 平台同理，用packwiz curseforge add <slug>即可，两条命令覆盖了两大主流平台。

场景二：一键刷新与批量更新

往整合包里手动添加过文件，或者想检查所有模组是否有新版本？先刷新索引，再批量更新：

packwiz refresh packwiz update --all

refresh会重新计算索引哈希，确保索引和实际文件一致；update --all则会检查所有带更新来源的模组，列出可用更新并询问是否执行。更新后索引自动重算，整个流程一气呵成，完全不用手动触碰 JAR。

场景三：本地起服务，模拟在线分发

整合包做出来后，最终要放到 HTTP 服务器上让别人下载。正式发布前，可以用内置的开发服务器预览效果：

packwiz serve

它会在本机起一个 HTTP 服务，每次被访问时自动刷新索引，配合 packwiz-installer 就能模拟"客户端自动拉取并更新整合包"的完整流程，调试体验非常顺手。

四、packwiz 进阶技巧与调优

用顺手之后，这几个配置项能显著提升体验：

• 锁定版本防误更新：某些模组升级后会有不兼容问题，用packwiz pin <模组名>把它钉在当前版本，update --all会自动跳过它；想解禁时执行packwiz unpin即可。
• 放宽可接受版本范围：默认只匹配整合包指定的 MC 版本，但很多模组支持跨版本运行。用packwiz settings acceptable-versions加入额外版本号，比如让整合包兼容 1.20.x 全系列，能减少"找不到兼容版本"的报错。
• 善用--yes非交互模式：在 CI 脚本或批量任务里，加-y参数会自动接受所有默认选项，方便自动化构建。
• 注意目录结构：添加的元数据文件默认按类型放进mods/、resourcepacks/等子目录，配合--meta-folder-base可以把它们统一收进子文件夹，保持仓库整洁。

五、packwiz 常见问题排查与避坑指南

Q1：init时报"metadata file already exists"？说明当前目录已有整合包文件。确认要重建就加-r参数覆盖，否则换一个空目录操作。

Q2：添加模组时提示"not available for the configured Minecraft version"？模组不支持当前 MC 版本。按上文进阶技巧调整acceptable-versions，或者改用其他兼容版本的模组。

Q3：update时提示某个文件找不到对应的更新系统？只有来自 Modrinth、CurseForge 等受支持来源的模组才能自动更新。手动塞进来的本地 JAR 没有更新元数据，属于正常现象。

Q4：多人协作时索引冲突？index.toml是纯文本，git 冲突可以手动合并。合并后务必运行packwiz refresh重算哈希，否则客户端可能校验失败。

避坑清单：

• 别把下载好的 JAR 直接提交进仓库，元数据才是 Git 管理的主体；
• 每次手动改过mods/下的文件，记得先refresh再提交；
• 发布到公网前，用serve完整走一遍客户端安装流程，避免"本地能用、线上报错"。

六、写在最后

如果说传统整合包维护是"搬运工"，那 packwiz 更像是你的"仓库管理员"——它把版本、依赖、更新这些最烦人的环节全部自动化，让你把精力留给真正有价值的内容创作。无论是给朋友分享私人整合包，还是为服务器长期维护模组列表，它都是当前生态里值得投入学习的一环。想深入了解格式规范与更多命令细节，可以继续研读仓库中的core/、modrinth/、curseforge/等核心模块源码，或者直接 clone 项目仓库https://gitcode.com/gh_mirrors/pa/packwiz边看边试，上手成本远比想象中低。

【免费下载链接】packwizA command line tool for editing and distributing Minecraft modpacks, using a git-friendly TOML format. Supports CurseForge and Modrinth mods with automated updates!项目地址: https://gitcode.com/gh_mirrors/pa/packwiz