企业官网建设流程全解析

• 游戏开发
• 插件系统

ArchiveXL 是一款 Cyberpunk 2077 MOD 资源扩展插件，能让多个 MOD 在不触碰原始游戏文件的前提下扩展同一资源（实体工厂、本地化文本、子网格可见性、视觉标签等），彼此之间不会产生冲突。当你按照文档打包好.archive文件却发现资源"凭空消失"时，问题往往出在三个环节：日志没看、Bundle 目录不对、Depot（ResourceDepot）里根本没有你的资源。本文给出一份从日志排查到 Depot 检查的完整排错清单。

先理解：ArchiveXL 是如何加载资源的

排错之前，先花 1 分钟搞清楚加载链路，后面每一步检查都对应链路上的一个环节：

1. 插件启动→ 输出ArchiveXL x.x.x is starting...（src/App/Application.cpp）
2. 注册 Bundle 目录→<插件目录>/Bundle会被注册为额外的 archive 目录（src/App/Environment.hpp）
3. 挂钩游戏资源库→ 在游戏的ResourceDepot::InitializeArchives之后插入自己的加载逻辑，把.archive文件按"Mod 作用域"分组载入 Depot（src/App/Archives/ArchiveService.cpp）
4. 发现扩展配置→ 递归扫描 Mod 目录里的.xlYAML 配置文件，交给各功能模块处理（src/App/Extensions/ExtensionLoader.cpp）

记住这条链路：Bundle 目录 → .archive 归档 → Depot 分组 → .xl 配置生效，任何一环断掉，资源就不会出现在游戏里。

排错第 1 步：找到日志并开启调试输出

所有问题的第一现场都是日志文件。ArchiveXL 的日志由内置的 Spdlog 轮转日志系统生成（lib/Support/Spdlog/SpdlogProvider.cpp），有几个关键事实：

⚠️ 如果目录里连ArchiveXL.log都没有，说明插件根本没被 RED4ext 加载——先检查 RED4ext 版本是否1.31.0+、游戏是否为2.5，这与 ArchiveXL 的兼容要求一致（见 README.md）。

开启调试输出：默认日志只记录 Info 级别。需要更详细的 trace 日志时，在插件目录的ArchiveXL.yaml中设置：

logging: debug: true

配置文件结构可参考 config/Config.yaml，读取逻辑见 src/App/Configuration.hpp。

排错第 2 步：对照日志关键语句定位断点

在日志里搜索以下语句，可以精确判断卡在哪一环。以下是排错中最常见的日志消息对照表：

💡 小技巧：[FactoryIndex]、[Localization]、[Mesh]等带模块前缀的行是各功能模块输出的，看到哪个模块报错，问题就集中在该模块的配置上。

排错第 3 步：检查 Depot（ResourceDepot）里的实际状态

如果日志显示 archive 已加载、扩展也配置成功了，但游戏内依然看不到资源，就要直接检查Depot——游戏运行时的资源数据库。

1. 确认你的 archive 进入了 Mod 分组

ArchiveXL 会为每个 Mod 目录在 Depot 中创建（或复用）一个scope = Mod的ArchiveGroup，你的 archive 挂在这个分组下（src/App/Archives/ArchiveService.cpp）。可以通过日志中的分组顺序确认自己的分组是否排在游戏原始分组之后——ArchiveXL 会保证 Mod 分组插在第一个非 Mod 分组之前，这是正确行为。

2. 用资源存在性检查定位具体路径

各模块最终都依赖 Depot 的"资源是否存在"查询来工作，例如 FactoryIndex 模块对每个声明的工厂路径执行存在性检查，不存在则跳过并打印上表中的doesn't exist. Skipped.（src/App/Extensions/FactoryIndex/Extension.cpp）。排错时按同样思路自查：

• ✅ 路径分隔符是否统一使用反斜杠\（RED4 引擎资源路径规范）
• ✅ archive 内部文件布局是否与声明的相对路径一致（参考 bundle/source/raw/ 中的资源树示例：characters/、common/等目录层级）
• ✅.xl配置里声明的factories/localization路径，前缀必须是你 archive 内的实际相对路径，可对照官方模板 support/templates/mod.archive.xl
• ✅ 资源类型与后缀匹配（CSV、JSON、mi、mesh 等）

3. 确认 .archive 文件本身有效

.archive是 RED4 引擎的资源归档格式。如果 archive 损坏或结构不对，ResourceDepot::LoadArchives会静默跳过，日志里只表现为"没有对应的 loaded 行"。用能正常工作的最小 archive（只放一个文本资源）替换验证，可快速区分"打包问题"还是"配置问题"。

排错第 4 步：检查常见配置陷阱

按出现频率从高到低：

1. 文件放错目录。自定义资源应放在插件目录下的Bundle/；旧的Archive/目录已废弃，插件启动时会直接清理（src/App/Migration.hpp、src/App/Environment.hpp）。放错位置 = 永远不会被加载。
2. .xl配置后缀错误。扩展发现器只扫描.xl后缀的 YAML 文件（src/App/Extensions/ExtensionService.cpp），.yml、.yaml都会被打回。
3. 脚本注册时机错误。通过 redscript 调用RegisterDir/RegisterArchive（定义见 scripts/Facade.reds）时，必须在 Depot 初始化之前完成，否则得到depot is already initialized错误。
4. 环境版本不匹配。RED4ext < 1.31.0、redscript < 0.5.32 或游戏非 2.5 版本，都会导致插件静默失效。
5. 本地化缺少回退语言。Localization 模块对当前语言找不到资源时会尝试回退语言，两者都缺失则静默跳过（src/App/Extensions/Localization/Extension.cpp）。

📋 排错清单（快速自查）

按顺序打勾，绝大多数"资源不加载"问题可以在这 8 步内解决：

• 插件目录下存在ArchiveXL.log（插件确实被加载了）
• ArchiveXL.yaml已开启logging: debug: true，复现一次问题
• 日志中有Loading extra archives...
• 日志中每个.archive都有对应的Archive "..." loaded.
• 资源文件位于Bundle/目录，archive 内相对路径与.xl声明一致
• .xl配置后缀正确、YAML 缩进无误
• 脚本注册的 archive/directory 发生在游戏早期，无depot is already initialized
• 无Failed to load/Resource "..." failed to load级别的模块错误；有则按模块名定位

完成以上检查后问题依然存在时，把完整的时间戳日志文件（而不是ArchiveXL.log软链接）连同最小复现 archive 一起反馈给开发者，能极大加速定位。

更多功能用法（动态外观、视觉标签、组件覆盖等）可参考项目文档入口：README.md 中的 Documentation 章节；资源路径注册机制见 src/App/Shared/ResourcePathRegistry.cpp。

• 游戏开发
• 插件系统