本教程根据 packwiz 官方网站（及其全部链接页面）整理翻译而成，涵盖：软件介绍、安装方法、创建与管理整合包、分发与发布、命令参考、包格式（TOML 元数据）详解。

原文：https://packwiz.infra.link/ 源码：https://github.com/packwiz/packwiz

1. packwiz 是什么
2. 安装 packwiz
3. 快速上手：创建整合包
4. 添加模组与资源包
5. 配合 Git 使用
6. 使用 packwiz-installer 安装与分发
7. 发布到 CurseForge
8. 发布到 Modrinth
9. 附加选项（pack.toml 的 [options] 段）
10. 命令参考
11. 包格式详解
12. 命令速查表（Cheat Sheet）

packwiz 是一个用于创建 Minecraft 整合包（Modpack）的命令行工具。它不直接管理 JAR 文件，而是创建 TOML 格式的元数据文件，这些文件易于进行版本控制，并且可以通过 Git 分享（可参考官方示例整合包：https://github.com/packwiz/packwiz-example-pack ）。

之后你可以：

• 把它导出为 CurseForge 或 Modrinth 格式的整合包；
• 或者使用 packwiz-installer（Java 编写）创建支持自动更新的 MultiMC 实例。

packwiz 擅长：

• 为服务器分发私有整合包；
• 创建发布到 CurseForge 和 Modrinth 的整合包。

packwiz 不擅长：

• 管理已下载的模组文件（这种情况建议使用 Curse 客户端、GDLauncher 或其他 CLI 工具，参见 https://gist.github.com/comp500/13ae6f058221196077fb19953ac608c7 ）；
• 为希望使用图形界面（GUI）的用户服务（虽然有第三方 GUI 项目：https://github.com/ExoPlant/packwiz-gui ）。

需要帮助可以加入作者的 Discord 服务器：https://discord.gg/Csh8zbbhCt

• 对 Git 友好的 TOML 元数据格式
• 基于 Java 的整合包安装器/更新器（兼容 MultiMC 和 ATLauncher），支持可选模组和快速自动更新——非常适合服务器！
• 通过 HTTP 服务器分发整合包，内置本地测试服务器
• 从 CurseForge 和 Modrinth 批量安装、更新多个模组
• 导出为 CurseForge / Modrinth 整合包
• 从 CurseForge 整合包导入
• 支持仅服务端 / 仅客户端模组
• 从 JAR 文件为 CurseForge 模组生成远程文件元数据

预编译二进制文件可以从 GitHub Actions 下载：https://github.com/packwiz/packwiz/actions

该页面 UI 比较简陋：选择列表最顶部的构建，然后在页面底部下载对应你系统的 artifact zip 包。

下载后，把可执行文件所在的文件夹加入系统的 PATH 环境变量（Windows 教程见 https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/ ），或者把可执行文件移动到你想使用的目录中。

如果没有 GitHub 账号，或无法直接从 GitHub 下载，也可以使用 nightly.link 下载最新的自动构建产物：

https://nightly.link/packwiz/packwiz/workflows/go/main

1. 安装 Go（1.19 或更新版本），下载地址：https://golang.org/dl/
2. 运行命令（请耐心等待，需要下载并编译依赖）：

go install github.com/packwiz/packwiz@latest

使用 packwiz CLI 前，先创建一个用于开发整合包的文件夹：

• 不要使用你的 .minecraft 文件夹或 MultiMC 实例文件夹；
• 这个文件夹存放整合包的元数据和文件，由 packwiz 管理。

然后在命令行（Windows 的命令提示符 / 其他系统的 Terminal）中用 cd 命令进入该文件夹。

在文件夹内直接运行：

packwiz init

它会向你询问一些细节，然后根据你的回答生成 pack.toml 和 index.toml 两个文件。

• pack.toml：整合包的主文件，定义关键信息——整合包名称、Minecraft 版本、模组加载器版本。可选地还可以包含版本号（导出为 Modrinth 整合包时必需）和描述。
• index.toml：整合包的索引文件，列出整合包中的所有文件及其哈希（用于完整性校验）。通常不需要手动修改它，但当手动添加、删除或修改包内文件后，需要运行 packwiz refresh 命令刷新索引。

如果你有现成的 CurseForge 整合包，可以使用 packwiz curseforge import 命令，传入整合包 .zip 的路径，即可把包内所有模组和文件导入当前目录：

packwiz curseforge import [zip 路径]

⚠️ 警告

• 如果整合包中已有文件，导入操作会覆盖它们；
• 如果导入的不是你自己的整合包，请确保你拥有重新分发它的许可/授权；
• 强烈建议使用版本控制系统（如 Git）配合 packwiz 使用！

快速总结最有用的命令（后续章节会有详细说明）：

任何命令都可以加 --help 查看详细信息！

要向整合包添加外部文件（如模组、资源包），需要 .pw.toml 格式的元数据文件来定义如何下载它们。modrinth install 和 curseforge install 命令可以自动生成这些文件（包含全部所需元数据）。

使用 modrinth install 和 curseforge install 命令即可轻松添加模组与资源包，还可以用 packwiz update 命令更新，加 --all 参数一次更新全部。

模组可以用多种形式传入命令：

CurseForge（packwiz curseforge install）

packwiz curseforge install indium                                   # 按 slug
packwiz curseforge install --category texture-packs unity           # 按 slug，并指定分类与游戏
packwiz curseforge install https://www.curseforge.com/minecraft/mc-mods/indium                  # 按模组页面 URL
packwiz curseforge install https://www.curseforge.com/minecraft/mc-mods/indium/files/3535202   # 按文件页面 URL
packwiz curseforge install Indium                                   # 按名称搜索
packwiz curseforge install --addon-id 459496 --file-id 3535202      # 其它办法都不行时，按 ID 指定

Modrinth（packwiz modrinth install）

packwiz modrinth install indium                                          # 按 slug
packwiz modrinth install https://modrinth.com/mod/indium                 # 按模组页面 URL
packwiz modrinth install https://modrinth.com/mod/indium/version/mfNlBb6U # 按文件页面 URL
packwiz modrinth install Fabric Rendering Sodium                         # 按名称搜索
packwiz modrinth install Orvt0mRa                                        # 按 ID

依赖自动处理：依赖项会自动识别——如果还没有安装，会提示你是否安装。packwiz 还会检查模组是否装错了 Minecraft 版本；如需允许更多版本，可在 pack.toml 中设置 acceptable-game-versions 字段（见下文）。例如在 pack.toml 底部加上：

[options]
acceptable-game-versions = ["1.16", "1.16.1", "1.16.2", "1.16.3", "1.16.4"]

💡 提示：curseforge 和 modrinth 命令存在多个别名以加快操作速度，例如 packwiz cf add 或 packwiz mr add！

整合包的配置文件可以直接放在 config 文件夹中（与 mods 文件夹同级），安装整合包时会被复制到游戏目录对应的 config 文件夹。这适用于任何文件（包括任务/脚本类文件）——把它放进整合包，安装时就会安装到游戏文件夹的对应位置。记得运行 packwiz refresh 让索引保持最新！

对于网上其他地方找不到的模组（例如自制的模组或分支），也可以直接把它们放进 mods 文件夹，与 .pw.toml 文件放在一起。不过这对 Git 不太友好（Git 不擅长处理大型二进制文件）；你可以使用 Git LFS，或者把它们手动上传到别处并在整合包中引用（见下节）。

💡 提示：如果不想把某些文件包含进整合包，可以在整合包目录中创建一个名为 .packwizignore 的文件，其格式与 .gitignore 相同（参见官方示例整合包）。

如果外部文件/模组不是来自 CurseForge 或 Modrinth，就需要手动创建 .pw.toml 文件。以下是一个示例：

name = "Flamingo"
filename = "flamingo.jar"
side = "both"

[download]
url = "https://example.com/flamingo.jar"
# 很多工具可以帮你生成哈希，包括 7-zip 和 sha256sum
# packwiz 支持多种哈希：sha256、sha512、sha1、md5 等
hash-format = "sha256"
hash = "b22d1d8fe5752533954028172c9bf3ac01b57f40c82946a3e7b1eaff389e2b87"

你也可以为非模组文件（如资源包）创建这样的文件——只要使用 .pw.toml 扩展名，并运行 packwiz refresh，packwiz 就会知道该文件包含元数据。

在 Windows 上，行尾符转换（line ending conversion）会导致文件上传到 Git 后哈希发生变化，安装整合包时会得到“哈希无效”的错误。此时需要添加一个 .gitattributes 文件来禁用行尾符转换。

可以参考官方示例整合包（https://github.com/packwiz/packwiz-example-pack ）中的 .gitignore 和 .gitattributes 示例文件。

如果 Git 中已经提交了已有文件，添加 .gitattributes 之后需要运行一次：

git add --renormalize .

来重置行尾符转换。

packwiz-installer（https://github.com/packwiz/packwiz-installer ）是一个基于 Java 的安装器，可以实现 packwiz 整合包的自动安装和更新！

• 可以配合 MultiMC / ATLauncher 作为**启动前任务（prelaunch task）**使用；
• 也可以用于服务器启动脚本；
• 支持仅单端模组（side-only mods）和带漂亮 GUI 的可选模组。

要分发 packwiz 整合包，首先需要搭建一个 Web 托管服务（如 Netlify、GitHub Pages、GitLab Pages），使整合包文件可以通过 HTTP/HTTPS 链接访问。

本地测试时，可以使用 packwiz serve 命令运行一个本地 HTTP 服务器，整合包会通过 http://localhost:8080/pack.toml 提供；它会在每次被请求时自动刷新索引，无需手动刷新！

将整合包作为 MultiMC 实例分发：

1. 创建一个极简的 MultiMC 实例，设置好想要的模组加载器和 Minecraft 版本（建议同时设置内存分配覆盖）；

2. 从 https://github.com/packwiz/packwiz-installer-bootstrap/releases 下载 packwiz-installer-bootstrap，放入实例的 Minecraft 文件夹；

   说明：这个文件夹与 options.txt 在同一目录，MultiMC 根据系统不同将其称为 .minecraft 或 minecraft。

3. 进入 Edit Instance → Settings → Custom commands，勾选 Custom Commands 复选框，在启动前命令（pre-launch command）栏粘贴以下命令（把 https://[your-server]/pack.toml 换成你的 pack.toml 实际托管地址）：

"$INST_JAVA" -jar packwiz-installer-bootstrap.jar https://[your-server]/pack.toml

4. 使用 Export Instance（导出实例）功能把整合包导出为 .zip 文件（可像整合包本身一样通过 Web 托管服务分发）。

用户安装时，只需 Add instance → Import from zip（添加实例 → 从 zip 导入），之后 packwiz-installer 会自动完成其余工作——每次启动游戏时保持整合包更新！

可以使用 packwiz-installer 下载非客户端模组（side 为 both 或 server 的模组），例如：

java -jar packwiz-installer-bootstrap.jar -g -s server https://[your-server]/pack.toml

• -g 标志：禁用 GUI；
• -s server：只下载服务端模组。

另外，itzg 的 docker-minecraft-server（https://github.com/itzg/docker-minecraft-server ）内置了对 packwiz 的支持：设置环境变量 PACKWIZ_URL 指向整合包的 TOML 文件，容器会自动引导 packwiz-installer 并安装/更新整合包。详见其文档：https://docker-minecraft-server.readthedocs.io/en/latest/mods-and-plugins/packwiz/

导出 CurseForge 整合包只需运行：

packwiz curseforge export

这会在整合包文件夹中生成一个 .zip 文件，可以直接上传到 CurseForge！

需要注意的几点：

• CurseForge 包格式不支持仅单端模组，所以 packwiz 无法创建服务端/客户端有差异的包。可以使用 --side 标志指定导出哪些模组——默认导出客户端包（包含 side 为 client 或 both 的模组）。
• 缺少 CurseForge 元数据的模组（例如从 Modrinth 安装的模组）会被以 JAR 形式放入整合包 zip；这些模组需要 CurseForge 工作人员人工审核批准（参见 https://support.curseforge.com/en/support/solutions/articles/9000197913-non-curseforge-mods ）。
• 注意不要把不想要的文件打进包里（例如 packwiz 可执行文件、以及整合包 zip 本身）！
• CurseForge 包格式不太支持可选模组。用户不会被询问可选模组，但如果它们默认是禁用的，那么在 CurseForge 启动器中就会保持禁用。

导出 Modrinth 整合包同样简单，运行：

packwiz modrinth export

这会在整合包文件夹中生成一个 .mrpack 文件，可以直接上传到 Modrinth！

与 CurseForge 不同，Modrinth 包格式支持仅单端模组。导出时，packwiz 会根据 Modrinth 提供的信息或模组 mod.pw.toml 中指定的信息导出。官方 Modrinth 启动器会自动过滤服务端模组，并且该包也可以通过 mrpack-install（https://support.modrinth.com/en/articles/8802250-modpacks-on-modrinth ）或 packwiz-installer 在服务器上使用。

需要注意的几点：

• 缺少 Modrinth 元数据的模组（例如从 CurseForge 安装的模组）会被以 JAR 形式放入整合包 zip；作为整合包作者，你有责任确保拥有这些模组的分发许可（参见 https://support.modrinth.com/en/articles/8797527-obtaining-modpack-permissions ）。
• 注意不要把不想要的文件打进包里（例如 packwiz 可执行文件、以及整合包 zip 本身）！
• 官方 Modrinth 应用不支持可选模组，用户不会被询问可选模组，而且官方启动器会自动安装全部可选模组（即使它们默认是禁用的！）。如果希望使用可选模组，可以使用 Prism Launcher 的 “Import Instance”（导入实例）功能安装导出的 .mrpack 文件。注意：如果用 Prism Launcher 的 “Modrinth” 区域安装整合包，同样不会提示可选模组。

附加选项可以在 pack.toml 的 [options] 段中配置：

mods-folder 已废弃，现在它是 meta-folder 的别名。

packwiz
A command line tool for creating Minecraft modpacks

全局选项（所有子命令都继承）：

--cache string               packwiz 缓存已下载模组的目录（默认 "<用户目录>/.cache/packwiz/cache"）
--config string              使用的配置文件（默认 "<用户目录>/.config/packwiz/.packwiz.toml"）
-h, --help                   help for packwiz
--meta-folder string         新元数据文件添加到的文件夹，默认基于分类（mods、resourcepacks 等；分类未知时用当前目录）
--meta-folder-base string    解析 meta-folder 的基准文件夹，默认为当前目录（默认 "."）
--pack-file string           使用的整合包元数据文件（默认 "pack.toml"）
-y, --yes                    所有提示都用默认值或 "yes" 接受（非交互模式）——可能在搜索结果中选择不想要的选项

子命令总览：

初始化一个 packwiz 整合包。

packwiz init [flags]

列出整合包中的所有模组。

packwiz list [flags]

刷新索引文件。

packwiz refresh [flags]

运行本地开发服务器——运行一个本地 HTTP 服务器用于开发，被查询时自动刷新索引。

packwiz serve [flags]

更新整合包中的一个（或全部）外部文件。

packwiz update [name] [flags]

packwiz remove [flags]     # 从整合包移除外部文件；等价于手动删除文件后运行 packwiz refresh
packwiz pin [flags]        # 固定一个文件，使其不会被自动更新
packwiz unpin [flags]      # 取消固定文件，使其可以接收更新

管理整合包设置。

packwiz settings [flags]

子命令：

• packwiz settings acceptable-versions：管理整合包可接受的 Minecraft 版本，必须是逗号分隔的版本列表，例如 1.16.3,1.16.4,1.16.5。

packwiz settings acceptable-versions [flags]

把 Minecraft 和加载器版本迁移到更新版本。

packwiz migrate loader [version|latest|recommended] [flags]   # 把模组加载器版本迁移到更新版本
packwiz migrate minecraft [version] [flags]                   # 把 Minecraft 版本迁移到更新版本

从直接下载链接添加外部文件，用于 packwiz 不直接支持的网站。

packwiz url add [name] [url] [flags]

packwiz curseforge [flags]

子命令：

• packwiz curseforge add [URL|slug|search] [flags]：从 CurseForge URL、slug、ID 或搜索添加项目。

• packwiz curseforge detect：检测 mods 文件夹中的 .jar 文件（实验性）。会自动检测可通过 CurseForge 获取的文件，并把它们改为从 CurseForge 下载。
• packwiz curseforge export：把当前整合包导出为 CurseForge 的 .zip。

• packwiz curseforge import [modpack path]：从下载好的整合包 zip 或已安装的元数据 json 文件导入 CurseForge 整合包。
• packwiz curseforge open [name]：在浏览器中打开 CurseForge 文件的项目页面。

packwiz modrinth [flags]

子命令：

• packwiz modrinth add [URL|slug|search] [flags]：从 Modrinth URL、slug/项目 ID 或搜索添加项目。

• packwiz modrinth export：把当前整合包导出为 Modrinth 的 .mrpack。

生成 Markdown 文档（你现在正在读的这类文档就是这么生成的）。

packwiz utils markdown [flags]

为指定 shell 生成自动补全脚本，支持：bash、fish、powershell、zsh。

packwiz completion [bash|fish|powershell|zsh]

pack.toml 是 packwiz 整合包的主文件。这是第一个被加载的文件，以便整合包下载器下载整合包中的所有文件。

关于整合包索引文件的信息。

本整合包使用的组件版本——通常指 Minecraft 和模组加载器。

index.toml 是整合包的索引文件，保存对整合包中每个待下载文件的引用。

一个通过 URL 引用外部文件的元数据文件。它可以实现仅单端模组（side-only mods）、可选模组（optional mods），并存储用于从 Modrinth 和 CurseForge 查找更新的元数据。这里大量使用 “mod”（模组）一词，但对任何文件都适用。

curseforge（更新源）

modrinth（更新源）

• packwiz 官方文档：https://packwiz.infra.link/
• packwiz 源码：https://github.com/packwiz/packwiz
• packwiz-installer：https://github.com/packwiz/packwiz-installer
• packwiz-installer-bootstrap 发布页：https://github.com/packwiz/packwiz-installer-bootstrap/releases
• 官方示例整合包：https://github.com/packwiz/packwiz-example-pack
• 第三方 GUI：https://github.com/ExoPlant/packwiz-gui
• 作者 Discord：https://discord.gg/Csh8zbbhCt