企业官网建设流程全解析

• 游戏开发
• 插件系统

📌ArchiveXL是一款 Cyberpunk 2077 的 Mod 资源扩展插件，允许多个 Mod 无冲突地扩展同一游戏资源。它的版本兼容机制通过Require(version)函数与semver语义化版本库实现：本篇带你从解析、比较到构建注入，完整读懂这套机制的设计与使用方式。

为什么 Mod 需要版本兼容检查

在 2077 的 Mod 生态中，一个插件往往会被其他 Mod 依赖（例如 ArchiveXL 被大量资源类 Mod 调用）。当宿主插件升级后，旧 Mod 可能因行为变化而出错；反过来，新 Mod 也需要确认"当前环境里的 ArchiveXL 是否足够新"。

ArchiveXL 为此提供了一个极简契约：调用方声明最低版本要求，宿主用一条比较语句回答"是或否"。

Require(version)：一次调用完成"解析 + 比较"

整个机制的核心只有几行代码，位于 src/App/Facade.cpp：

bool App::Facade::Require(Red::CString& aVersion) { const auto requirement = semver::from_string_noexcept(aVersion.c_str()); return requirement.has_value() && Project::Version >= requirement.value(); }

执行逻辑分两步：

💡 设计亮点：from_string_noexcept是"安全解析"版本——遇到"1.2"这类不合法输入时静默返回空值，而不是让游戏内脚本层抛出异常。调用方拿到false后自行降级处理即可。

配套的 GetVersion() 则返回当前版本号字符串（to_string()输出），方便 Mod 日志中打印诊断信息。

semver：语义化版本如何解析与比较

ArchiveXL 使用的 semver 库是一个头文件-only的第三方库，以 vendor 形式内置在仓库中：

• 依赖声明：xmake.lua 中定义了名为semver的 headeronly 目标，指向vendor/semver/include/semver.hpp
• 全局引入：src/pch.hpp 直接#include <semver.hpp>，所有源文件开箱即用

SemVer 的核心约定是主版本.次版本.修订号（如1.28.1）：

• major变化 → 不兼容的 API 变更
• minor变化 → 向下兼容的新功能
• patch变化 → 向下兼容的缺陷修复

Require("1.20.0")的语义即"当前版本至少是 1.20.0"，因此 1.28.1 满足、1.19.0 不满足，比较时逐段按数值顺序判断，无需字符串比对。

版本号从哪里来：构建时自动注入

版本号并非硬编码在业务代码里，而是由构建系统统一注入，全仓库单一事实来源：

1. 在 xmake.lua 声明set_version("1.28.1", {build = "%y%m%d%H%M"})

2. 构建时渲染模板 config/Project.hpp.in，生成头文件并写入：

   constexpr auto Version = semver::from_string_noexcept("${VERSION}").value();

   即编译期就把版本号固化成常量，运行时零成本。

3. 同时渲染 config/Version.rc.in，把major.minor.alter.build四段版本写入 Windows DLL 资源信息，在系统"文件属性"中也能看到正确的版本。

这种"模板 + 构建期渲染"的做法避免了改一处版本漏改另一处的经典错误。

Mod 开发者怎么调用：脚本与 C++ 双入口

🎮 脚本层（RedScript）

scripts/Facade.reds 向脚本系统暴露了两个静态方法：

public static native func Require(version: String) -> Bool public static native func Version() -> String

结合 src/App/Facade.hpp 中的 RTTI 注册，脚本 Mod 可以直接这样写：

if (ArchiveXL.Require("1.28.0")) { // 使用新版 API } else { // 回退到兼容路径或提示用户更新 }

🧩 C++ 层（RED4ext 插件）

C++ Mod 则通过官方 SDK 头文件 support/red4ext/ArchiveXL.hpp 注册资源包。值得注意的是它内置了一道前置兼容性探测：通过 RTTI 查找ArchiveXL类及其Version方法，找不到就说明宿主未加载或不匹配，自动进入"排队等待"模式，等 Facade 就绪后再注册——这与Require形成互补的防御层次。

真实案例：ArchiveXL 自己也用它检测 Codeware

这套机制是生态级契约，ArchiveXL 自身也在消费它。在 InkSpawner 扩展 src/App/Extensions/InkSpawner/Extension.cpp 中：

• 启动时调用Codeware.Require("1.14.0")
• 若新版 Codeware 已接管相关功能，则跳过自身的 Hook，避免双重处理
• 否则才挂接 widget 生成函数

一个bool返回值，就解决了 Mod 之间的共存与去重问题。

快速排错清单：Require 返回 false 怎么办？

总结

ArchiveXL 的版本兼容机制可以浓缩为三句话：

1. 构建期：xmake 把单一版本号注入Project::Version常量，DLL 资源信息同步生成；
2. 运行期：Require(version)用 semver 安全解析 + 一次大小比较给出结论，非法输入静默失败；
3. 生态面：脚本与 C++ 双入口统一契约，让 Mod 作者一行代码即可声明兼容范围，真正实现"资源扩展零冲突"。

对新手 Mod 作者的建议：把Require当作版本契约的守卫，在功能分支前统一拦截，比事后处理崩溃要优雅得多。

• 游戏开发
• 插件系统