FiveM FXAP 与 Asset Escrow：从资源打包到运行时授权

FiveM 的 Asset Escrow 是资源作者保护代码和资产的一套官方系统。它的目标是让授权用户可以运行资源，同时减少未经授权的直接访问和修改。

本文只记录公开文档、公开运行时行为和正确使用边界。不会提供密钥、Token、授权绕过或解密步骤。

Asset Escrow 保护什么

官方文档当前列出的支持类型包括：

类型	说明
Lua	资源脚本代码
YFT	模型文件
YDD	Drawable Dictionary
YDR	Drawable

NUI 当前不在官方 Asset Escrow 支持范围内。因此需要保护的界面逻辑、前端资源和服务端接口，仍然要通过正常的代码拆分、权限检查和发布策略处理。

从上传到运行的流程

一个典型的发布链路可以分成四步：

1. 作者在 Cfx.re Portal 创建 Asset，并上传压缩后的资源。
2. Portal 对资源进行处理，生成供授权分发的版本。官方文档当前标注最大上传文件为 1GB。
3. 作者可以通过 Portal 或 Tebex 将资源交付给拥有资格的服务器。
4. 服务器启动资源时，运行时检查目标服务器是否具备对应 entitlement。没有授权时，资源不会正常启动。

资源更新时，新上传版本会替换账户中的当前版本。已经下载旧版本的用户，仍然可能继续使用旧版本，因此发布前要明确版本兼容策略。

FXAP 与资源文件的关系

在实际资源目录和下载流程中，常能看到以 .fxap 标识的受保护文件或控制信息。它不是一个应该被站点当作普通文本展示的源码格式，而是 Asset Escrow 资源链路中的受保护产物。

更稳妥的理解方式是区分三个层次：

• 发布层：Portal 接收压缩资源并处理加密版本。
• 授权层：Tebex 或账户资格决定某个服务器是否可以使用资源。
• 运行层：FXServer 在启动资源时完成资格检查和加载决策。

公开文档没有给出内部密钥材料和完整加密算法细节。因此不应根据文件头、样本字节或某次下载结果臆测完整密码学实现。

fxmanifest.lua 与 escrow_ignore

作者可以在 manifest 中声明不需要被保护的文件。例如配置、公开接口或需要让服务器方修改的部分，可以使用 escrow_ignore：

escrow_ignore {
  'config.lua',
  'shared/*.lua',
  'stream/tuner.ydr'
}

忽略范围应该尽量小。把核心逻辑全部放进忽略列表，会直接降低保护效果；把必须由服务器方配置的文件全部锁住，又会增加部署和排错成本。

常见错误和排查顺序

当控制台出现 You lack the required entitlement 时，优先检查：

1. 运行资源的服务器是否是购买或获授权的目标服务器。
2. Tebex 交付是否使用了正确的 Asset。
3. Portal 中的当前版本是否已经重新上传并处理完成。
4. 资源名、manifest 和部署目录是否与交付内容一致。
5. 服务器是否使用了过期的本地缓存或旧版本目录。

不要把这类错误当成普通 Lua 语法错误。授权失败发生在资源能够正常运行之前。

作者侧发布清单

• 在干净服务器上验证资源能启动。
• 确认 escrow_ignore 没有覆盖核心文件。
• 给配置文件和公开 API 写出清楚的使用说明。
• 在 Tebex 包中交付正确 Asset，并记录版本号。
• 为更新保留可回滚的本地构建产物。
• 不在公开仓库、文章、日志或截图中放置 Token、密钥和服务器私有信息。

参考资料

• Cfx.re Asset Escrow 官方文档
• CitizenFX/FiveM 开源仓库

本文最后核验：2026-07-15。官方功能和支持范围可能变化，发布资源前应重新查看官方文档。