QBCore、ESX 或独立：Agency Scripts 如何与您的框架协作

框架兼容性问题

大多数 FiveM 脚本内置绑定一个框架。运行 QBCore 就用 QBCore 脚本，ESX 用户只能用 ESX 脚本，独立用户大多自行拼凑。Agency Scripts 采用相反理念：框架是适配器，而非假设。

适配器模式

每个Agency脚本都暴露一小组查找函数： getPlayerData, getInventory, addMoney, removeItem, getJob我们提供适配器，开箱即用地映射到QBCore和ESX实现。对于standalone，您需自行实现四到五个函数，通常一上午的工作，每个Agency脚本均兼容。

这在实践中意味着什么

当您将服务器从 QBCore 切换到 ESX（框架演进中每隔几年会发生），Agency 脚本无需重新安装或配置。只需更换适配器，其他功能继续正常。这在 FiveM 生态中极为罕见，也是服务器所有者长期标准化使用我们工具的主要原因。

我们产品页面上的框架标签代表什么

当产品页面列出“QBCore, ESX”时，表示我们提供两者的现成适配器。标注“Standalone”则表示脚本框架无关，免适配器，可在任何服务器运行。实际上几乎所有 Agency 脚本均可通过小型兼容层用于独立架构。

购买前何时询问

如果您运行不寻常的设置、自定义框架、经过大量修改的 QBCore 或定制内容，请在购买前在我们的 Discord 上提交工单。我们会诚实告诉您什么可行，什么需要轻微调整，什么不值得麻烦。无销售压力；我们宁愿您购买一个合适的脚本，也不愿您买三个不合适的。

适配器模式的实际工作原理

安装 Agency 脚本时，资源文件夹包含一个 framework 包含至少三个文件的子目录： qb.lua, esx.lua，和 standalone.lua. 主脚本通过检查 QBCore 或 ESX 导出自动检测所用框架。匹配的适配器文件加载，其他不加载。此自动检测在任何游戏逻辑运行前完成，无运行时开销。

每个适配器实现相同的内部API接口。如果脚本需要给玩家发钱，它调用 Framework.AddMoney(src, amount) 内部。该功能在 qb.lua 调用 QBCore 的资金导出；在 esx.lua 它调用ESX的账户系统；在 standalone.lua 它调用您在 config.lua. 一次调用，三种实现，框架间无需更改脚本。

QBCore上的安装

对于QBCore服务器，安装通常分三步：下载资源，放入resources文件夹，并添加到server.cfg。框架检测自动完成。如果你使用了显著修改的QBCore（自定义货币系统、自定义库存、自定义职业），可能需要覆盖特定适配器函数，详见 config.lua 而非编辑 qb.lua 直接。配置覆盖方法意味着资源更新时不会丢失你的更改。

ESX上的安装

ESX安装遵循相同模式。偶尔需要额外步骤：如果你的ESX版本显著较旧（1.7之前），部分适配函数引用了较新的ESX导出名称。该资源带有兼容旧版本的标志。 Config.ESXLegacy = true 切换到所有需要的 Agency 脚本中较旧的 ESX API 调用。

Standalone上的安装

独立版是大多数服务器所有者在使用其他脚本时遇到摩擦的地方。Agency Scripts 的独立路径明确且文档完善。每个脚本的独立适配器文件列出了你需要实现的具体函数。大多数脚本需要四到八个函数。每个函数都有注释说明应返回什么。典型的独立实现根据你的自定义玩家数据系统复杂度，耗时一到三小时。

实现一个Agency脚本的适配器后，后续脚本所需时间大大减少，许多自定义函数可跨多个资源复用。

为什么这对服务器长期运营至关重要

FiveM 框架并非永久。运营三年以上的服务器很可能已经经历过至少一次重大框架调整，可能是从社区 ESX 分支迁移到主线 ESX，或从旧版 QBCore 升级到当前版本。依赖框架绑定脚本的服务器迁移成本高昂：框架重大变更时，每个脚本都需更新或替换。

Agency Scripts' adapter architecture means that a framework migration affects only the adapter layer. Your Agency-Phone data, Agency-Admin logs, Agency-Blackmarket transaction history, and player progression in Agency-Minerjob all survive intact. You swap the adapter files, update config.lua, and the scripts keep working. This is the actual long-term value of the compatibility approach, not just supporting multiple frameworks, but insulating your server from framework evolution.

常见问题

所有 Agency 脚本都使用相同的适配器模式吗？

是的。每个付费Agency脚本和大多数免费脚本都采用此模式。唯一例外是纯UI资源，如Agency-Loadingscreen和Agency-Notify，它们完全无框架交互，且在所有环境中表现一致。

我可以混合使用框架适配器吗？例如，使用QBCore货币但独立库存？

是的，通过配置覆盖。将您的框架检测设置为QBCore，然后在config.lua中覆盖特定的适配器函数，以调用您的自定义库存系统而非QBCore的。覆盖系统正是为混合设置的服务器设计的。

如果出现新的流行框架但尚未支持怎么办？

在 Discord 上提交支持工单。我们根据社区采用情况评估新的框架支持请求。对于拥有大量社区的框架，我们历史上在 2-4 周内添加支持。与此同时，standalone 适配器路径可作为任何框架的临时解决方案。

框架适配器会在框架本身更新时更新吗？

是的。当 QBCore 或 ESX 发布重大变更时，我们会在框架发布后几天内推送适配器更新。活跃订阅者通过 Tebex 接收更新通知。这也是订阅模式存在的原因之一，适配器维护是持续工作，而非一次性费用。

各框架需求摘要

• QBCore，任何最近的QBCore版本。自动检测，标准设置零配置。
• ESX，ESX Legacy 1.7+ 或主线 ESX。旧版本请设置 legacy 标志。
• 独立版，在config.lua中为每个脚本实现4-8个函数。一次设置，可在Agency脚本间复用。
• 所有设置，具有有效许可证的cfx.re账户，推荐使用版本5181或更高的FiveM服务器。