如何快速掌握xnbcli：星露谷XNB文件打包解包工具全指南

xnbcli是一款专为星露谷设计的XNB文件打包解包工具，能够帮助玩家轻松处理游戏中的XNB格式文件，实现自定义资源的导入导出。无论是修改游戏纹理、音效还是其他资源，这款免费开源的命令行工具都能提供高效支持。

📌 为什么选择xnbcli？核心优势解析

作为星露谷模组开发和资源定制的必备工具，xnbcli具有三大核心优势：

• 专为星露谷优化：完美支持游戏所有LZX压缩格式的XNB文件
• 跨平台兼容：提供Windows（.bat）、macOS（.command）和Linux（.sh）版本的操作脚本
• 极简操作流程：无需复杂配置，通过预设脚本即可一键完成打包解包

📂 项目结构详解：轻松定位核心功能

xnbcli采用清晰的目录结构设计，主要功能模块一目了然：

xnbcli/
├── app/               # 核心功能代码目录
│   ├── Xnb/           # XNB文件处理核心模块
│   ├── Presser/       # LZX压缩算法实现
│   └── Xact/          # 音频资源处理模块
├── packed/            # 待解包文件存放目录
├── unpacked/          # 解包后文件输出目录
├── pack.bat/.sh       # 打包脚本（按系统选择）
└── unpack.bat/.sh     # 解包脚本（按系统选择）

🔑 核心目录功能说明

• app/Xnb/Readers/：包含20+种数据类型的读取器，支持Texture2D、SoundEffect等星露谷资源格式
• packed/：存放需要解包的XNB文件，运行解包脚本后自动处理
• unpacked/：解包后的原始文件存放位置，修改后可通过打包脚本生成新XNB

🚀 零基础入门：3步完成XNB文件处理

1️⃣ 环境准备：5分钟快速安装

前置要求：确保已安装Node.js环境（建议v14+版本）

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/xn/xnbcli

# 进入项目目录并安装依赖
cd xnbcli && npm install

2️⃣ 文件解包：释放星露谷资源

1. 将需要解包的XNB文件复制到packed目录
2. 根据操作系统运行对应脚本：
   • Windows用户：双击运行unpack.bat
   • macOS/Linux用户：终端执行./unpack.sh
3. 解包后的文件会自动输出到unpacked目录

💡 小技巧：通过npm run unpack命令也可快速执行解包操作，结果与脚本执行完全一致

3️⃣ 文件打包：生成可用XNB文件

1. 将修改后的资源文件放入unpacked目录（保持原始目录结构）
2. 运行打包脚本：
   • Windows用户：双击pack.bat
   • macOS/Linux用户：终端执行./pack.sh
3. 生成的XNB文件会保存到packed目录，可直接用于星露谷游戏

⚙️ 高级使用：自定义命令行操作

对于有一定技术基础的用户，xnbcli提供灵活的命令行接口：

# 基础语法
xnbcli (pack|unpack) [输入路径] [输出路径]

# 示例：解包单个文件
xnbcli unpack ./custom/menu.xnb ./output/

# 示例：打包整个目录
xnbcli pack ./modified_assets/ ./new_packed/

📝 package.json中的快捷脚本

项目已预设便捷npm脚本，简化日常操作：

• npm run unpack：快速执行解包流程
• npm run pack：一键打包unpacked目录下所有文件

❓ 常见问题解决

Q：解包失败提示"压缩格式不支持"？

A：确保XNB文件使用LZX压缩算法（星露谷标准格式），目前工具暂不支持其他压缩方式

Q：打包后的文件在游戏中无法加载？

A：检查unpacked目录结构是否与原始一致，资源文件名是否使用英文命名

📄 许可证信息

xnbcli采用LGPL-3.0许可证开源，允许商业使用和二次开发，但修改后的代码需保持开源。详细条款参见项目根目录下的LICENSE.md文件。

🌟 写在最后

无论是星露谷模组开发者还是普通玩家，xnbcli都能成为你定制游戏体验的得力助手。通过简单的文件操作，即可解锁无限的游戏自定义可能。立即下载体验，开启你的星露谷个性化之旅吧！

提示：项目持续维护中，建议定期通过git pull更新获取最新功能和bug修复。