Packwiz中文文档(非官方)

官方文档地址: https://packwiz.infra.link/ 项目仓库: https://github.com/packwiz/packwiz 介绍 packwiz 是一款用于创建 Minecraft 整合包的命令行工具。它不直接管理 jar 文件，而是创建 toml 元数据文件，这些文件

作者
炎霆
2026年8月30日
•
1 分钟阅读

官方文档地址: https://packwiz.infra.link/

项目仓库: https://github.com/packwiz/packwiz

介绍

packwiz 是一款用于创建 Minecraft 整合包的命令行工具。它不直接管理 jar 文件，而是创建 toml 元数据文件，这些文件易于进行版本控制，并可通过 git 进行共享（可在此处查看示例整合包）。之后，您可以将其导出为 CurseForge 或 Modrinth 整合包，或者使用 packwiz-installer 来自动更新 MultiMC 实例。

packwiz 非常适合用于...

为服务器分发私有整合包
为 CurseForge 和 Modrinth 创建整合包

packwiz 不太适合用于...

管理下载的模组文件（请使用 Curse/GDLauncher 或其他命令行工具）
需要图形用户界面的用户（尽管有一些第三方的努力成果）

功能特性

基于 toml 的元数据格式，对 Git 友好
基于 Java 的整合包安装程序/更新程序（兼容 MultiMC 和 ATLauncher），支持可选模组以及快速自动更新，非常适合服务器使用！
通过 HTTP 服务器分发整合包，并内置本地服务器用于测试
支持从 CurseForge 和 Modrinth 同时轻松安装和更新多个模组
导出为 CurseForge 和 Modrinth 整合包
从 CurseForge 整合包导入
仅服务器和仅客户端模组的处理
为 CurseForge 模组的 JAR 文件创建远程文件元数据

安装Packwiz

以下是你提供文本的中文翻译：

预编译的二进制文件可从 GithubAction https://github.com/packwiz/packwiz/actions获取——界面稍微有点糟糕，但基本上选择顶部的构建，然后在页面底部下载适用于你系统的产物（Artifact）zip 文件。要运行可执行文件，需将下载的文件夹添加到你的 PATH 环境变量中，或者将其移动到你想使用的位置。

未来我会提供更多的安装选项，但你现在也可以从源代码进行编译：

从 https://golang.org/dl/ 安装 Go（1.19 或更新版本）
运行 go install github.com/packwiz/packwiz@latest。请耐心等待，因为它还需要下载和编译依赖项！

创建整合包

要使用 packwiz 命令行工具，首先你需要创建一个文件夹来开发你的整合包。这个文件夹不应该与你的 .minecraft 文件夹或 MultiMC 实例文件夹相同；这个文件夹用于存放整合包的元数据和文件，以便 packwiz 进行管理。

然后，打开你的命令行（命令提示符/终端），使用 cd 命令进入你刚才创建的文件夹。

创建一个新的整合包

要在新文件夹中创建整合包所需的文件，只需运行 packwiz init 命令！程序会询问你一些细节，然后根据你的回答创建 pack.toml 和 index.toml 文件。

pack.toml 是你整合包的主要文件，它定义了几个关键细节，包括整合包的名称、Minecraft 版本以及你正在使用的模组加载器版本。你还可以选择性地包含整合包的版本号（导出到 Modrinth 整合包时必需）和描述信息。
index.toml 是你整合包的索引文件，它列出了整合包中的文件及其哈希值（用于完整性校验）。你通常不需要手动修改此文件，但当你手动向整合包中添加、删除或编辑文件时，你需要运行 packwiz refresh 命令来更新索引。

导入现有的整合包

你手头已经有了一个 CurseForge 整合包？你可以使用 packwiz curseforge import 命令，并提供整合包 .zip 文件的路径。该命令会将包内的所有模组和文件导入到你当前的目录中。

注意
如果你导入的不是你自己的整合包，请确保你拥有重新分发该整合包的权限（或相关许可）！

⚠ 警告

如果你的整合包文件夹中已存在文件，导入操作将会覆盖这些文件。建议你将 packwiz 与版本控制系统（例如 Git）配合使用，这是一个好习惯！

速查表

在后续的教程（以及参考页面）中你会获得更详细的信息，但这里是对最常用命令的快速总结：

packwiz init —— 在当前文件夹创建一个整合包
packwiz curseforge import [zip路径] —— 导入一个 CurseForge 整合包
packwiz refresh —— 更新整合包索引
packwiz curseforge install [模组名] —— 从 CurseForge 安装一个模组
packwiz modrinth install [模组名] —— 从 Modrinth 安装一个模组
packwiz update [模组名] —— 更新一个模组
packwiz update --all —— 更新整合包中的所有模组
packwiz curseforge export —— 将整合包导出为 CurseForge 启动器支持的格式
packwiz modrinth export —— 将整合包导出为 Modrinth（及其正在开发中的启动器）支持的格式
packwiz curseforge detect —— 检测哪些文件可以在 CurseForge 上找到，并使其从该处下载

使用 --help 参数可以查看关于任何命令的更多详细信息！

添加模组/资源包

要向你的整合包中添加模组（mods）和资源包（resource packs）等外部文件，你需要使用 .pw.toml 元数据文件来定义如何下载它们。modrinth install 和 curseforge install 命令可以自动为你创建这些文件，并填充所有必要的元数据！

CurseForge 和 Modrinth

你可以通过 modrinth install 和 curseforge install 命令轻松添加来自 CurseForge 和 Modrinth 的模组及资源包。你也可以使用 packwiz update 命令来更新它们；使用 --all 参数可以一次性更新你所有的模组。

这些命令支持以多种形式传递模组参数：

CurseForge 命令示例：

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 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 还会检查你的模组是否安装了错误的版本；但你可以通过在 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，以便索引保持最新！

这也适用于那些在网上其他地方无法找到的模组（例如自定义模组或分支版本）；只需将它们连同 .pw.toml 文件一起放入 mods 文件夹即可。但这对于 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 知道该文件包含元数据。

使用Git进行管理

在 Windows 系统下，换行符转换会导致文件上传到 Git 时哈希值发生变化，因此在尝试安装整合包时你会遇到“哈希值无效”的错误。你需要添加一个 .gitattributes 文件来禁用换行符转换。你可以查看示例整合包，其中包含了 .gitignore 和 .gitattributes 文件的示例！

如果你已经将现有文件提交到了 Git，那么在添加 .gitattributes 文件后，你需要运行 git add --renormalize . 命令，以重置已提交文件的换行符转换设置。

安装整合包

packwiz-installer 是一个基于 Java 的安装程序，它支持整合包的自动安装和更新！它可以作为预启动任务（prelaunch task）与 MultiMC/ATLauncher 配合使用，也可以作为启动脚本的一部分用于服务器端。它支持仅限特定端（side-only）的模组，以及带有精美图形界面（GUI）的可选模组。

要分发一个 packwiz 整合包，你首先需要设置一个网络托管服务（例如 Netlify、Github Pages、GitLab Pages），以便你的整合包文件可以通过 HTTP/HTTPS 链接访问。在测试阶段，你可以使用 packwiz serve 命令运行一个本地 HTTP 服务器，它会在 http://localhost:8080/pack.toml 提供你的整合包服务——每当索引被查询时它会自动刷新，因此你不需要手动刷新索引！

为你的整合包创建 MultiMC 实例

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

创建一个最基本的 MultiMC 实例，选择你想要的模组加载器（modloader）和 Minecraft 版本（调整内存分配也是个好主意）。

从 github.com/packwiz/packwiz-installer-bootstrap/releases 下载 packwiz-installer-bootstrap，并将其放入实例的 Minecraft 文件夹中。

这是与 options.txt 相同的文件夹。根据你的系统不同，MultiMC 会将其称为 .minecraft 或 minecraft。

进入 Edit Instance（编辑实例） -> Settings（设置） -> Custom commands（自定义命令），勾选 Custom Commands（自定义命令） 框，并将以下命令粘贴到 pre-launch command（预启动命令） 字段中：
"$INST_JAVA" -jar packwiz-installer-bootstrap.jar https://[your-server]/pack.toml
(其中 https://[your-server]/pack.toml 是你托管 pack.toml 文件的 HTTP URL)
使用 Export Instance（导出实例） 功能将你的实例导出为 .zip 文件（该文件可以通过网络托管服务像分发整合包一样分发）。

要安装你的整合包，用户只需通过 Add instance（添加实例） -> Import from 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 用于仅下载服务器端模组。

发布到Curseforge

导出 CurseForge 整合包非常简单，只需运行 packwiz curseforge export 命令即可——这会在你的整合包文件夹中生成一个 .zip 压缩包，你可以直接将其上传到 CurseForge！

由于这种整合包格式不支持仅限特定端（side-only）的模组，因此 packwiz 无法创建服务器端和客户端不同的整合包。你可以使用 --side 参数来指定应该导出哪些模组——默认情况下，它会为 Minecraft 客户端导出整合包（包含 side 为 client 或 both 的模组）。那些缺少必要 CurseForge 元数据的模组（例如从 Modrinth 安装的模组）将作为 JAR 文件直接放入整合包压缩包中；这些模组必须由 CurseForge 工作人员手动批准。

请注意不要包含你不想要的文件（例如 packwiz 可执行文件本身以及整合包 zip 压缩包）！

CurseForge 整合包格式实际上并不太支持可选模组。用户不会被提示选择可选模组，但如果这些模组默认是禁用的，它们在 CurseForge 启动器中也会处于禁用状态。（不过对于第三方启动器的支持情况我不太确定，因为我认为 CurseForge 的启动器通常不会导出已禁用的模组）

如需了解更少信息，请参阅相应的参考页面。

发布到Modrinth

导出 Modrinth 整合包非常简单，只需运行 packwiz modrinth export 命令即可——这会在你的整合包文件夹中生成一个 .mrpack 文件，你可以直接将其上传到 Modrinth！

与 CurseForge 不同，这种整合包格式确实支持仅限特定端（side-only）的模组。在导出时，packwiz 会根据 Modrinth 提供的端信息或模组 mod.pw.toml 文件中指定的信息进行导出。官方 Modrinth 启动器会自动过滤掉服务端模组，而该整合包也可以通过 mrpack-install 或 packwiz-installer 等工具用于服务器端。那些缺少必要 Modrinth 元数据的模组（例如从 CurseForge 安装的模组）将作为 JAR 文件直接放入整合包压缩包中；请务必确保你拥有这些模组的分发许可，因为作为整合包制作者，这是你的责任。