fivem-development

FiveM 开发 — 最佳实践

与框架无关的编排器。一个技能——按需加载参考文件（不要全部加载）。

语言规则： 内部推理使用简洁的英文。所有展示给用户的消息和输出都必须使用用户的语言。

理念

1. 获取，而非死记——不确定原生功能或 API 时，请通过权威来源核实
2. 采用与框架无关的思路——理解模式，并适配当前使用的框架
3. 性能优先——FiveM 的 tick 预算严格
4. 关注安全——服务端验证不可妥协
5. 选择简洁、易读的 Lua，而非抽象——优先使用单体结构（server.lua / client.lua），尽量少写注释，仅在重复使用（有 2 个或更多调用点；§3.11）时提取 local function。不要像 React 一样将 Lua 拆分为组件，也不要在 Tunnel/return 足以满足需求时，凭空设计事件往返。
6. 项目记忆——reference.mdc = 精简的全局地图（alwaysApply）；.fxmind/memory/<topic>.md = 共享的精简方案。重新扫描前运行 /fxmind learn；运行 /fxmind memory health；运行 /fxmind graph；运行 /fxmind query。
7. 审计力度——/fxmind audit 遵循 performance.md §1.6.1–§1.6.2 + audit-passes.md §2.3–§2.5（当存在 ui_page 时，Pass 2b E-a…E-g、Pass NUI N-a…N-d）+ security.md §5.1。
8. 质量门禁（任务模式）——实现或重构代码时遵循 quality-gates.md：在 Gate A 进行设计评审，在 Gate V 之前进行自我审查循环。

---

参考路由器（仅加载所需内容）

主题	文件	关键章节
隧道 / 事件 / _ 前缀 / 同侧调用 / 响应预算	communication.md	§1.1–§1.3, §1.7
循环、动态休眠、载荷、tunnel_res、广播、StateBags、缓存（服务端 + 客户端 §2.1.1）、视图缓存、客户端数据预置 / 引导 §2.2.1	performance.md	§1.4–§1.6.2, §2.1–§2.2.1, §4.1–4.2, §4.5
仅审计 — Pass 0–7、矩阵 V/E/N、报告门槛	audit-passes.md	§2.3–§2.5
单体布局、全局变量与伪模块、状态放置	architecture.md	§3.5–§3.6, §3.8
查找表、nil、注释、单次使用的辅助函数、检查清单、反模式	style.md	§3.1–3.4, §3.7, §3.9–§3.11
SafeEvent、SetCooldown、端点身份验证、服务端解析、输入验证	security.md	§4.6–4.8, §5.1–§5.3
cerberus 导出签名与示例	api.md	§4.3–4.4
实现 / 重构（任务模式 DoD）	quality-gates.md	Gate A 质量 + 自我审查循环
NUI / React UI（CEF 填充、Vite 哈希）	fivem-react-nui/SKILL.md · ui-guide.md §2, §6
所有 § 链接的索引	best-practices.md	仅目录
道具 / 载具 / 行人	asset-discovery.md	—
检测 vRP / QB / Qbox / ESX	framework-detection.md	—

原则 ID → 章节（ID 来自 .fxmind/policy/fivem-principles.md；仅打开所需行）：

ID	规则	详情
N1	接收者范围	performance §1.6.1, §4.2
N2	最小载荷	performance §1.6, §2.2
N3	大数据分块传输	performance §1.6, §2.2.1, §4.1–4.2（cerberus SendFullSync）
N4	不进行定期扇出	performance §1.4, §1.6.1, §4.2
N5	客户端同步 / statebags	performance §1.6.2, §2.1.1
N6	防洪泛	security §4.6–§4.8, §5.1
N7	通过服务端推送预置客户端数据	performance §2.2.1
D1	热路径中不访问数据库	performance §2.1, §2.1.1
D2	一次往返，不出现 N+1	performance §1.4
D3	服务端掌握事实	security §5.2–§5.3
T1/T2	事件驱动、动态休眠	performance §1.5
C1	代码精简，不使用单次使用的辅助函数	style §3.11–§3.12, communication §1.3
C2	流程清晰，不使用全局变量	architecture §3.5–§3.6, §3.8；style §3.1–§3.4
C3/C4	只验证一次；保持差异整洁	security §5.3；style §3.7, §3.9
C5	词法局部变量 / 被调用者先于调用者	style §3.11；architecture §3.8

待修正项（.fxmind/corrections/）的类别与这些文件一一对应——将规则归入匹配的文件，而不是新建技能。

---

重要：禁止臆造

绝不臆造或猜测原生函数、框架 API 或参数。

1. 不确定某个原生函数时 → 必须从 https://docs.fivem.net/natives/ 获取信息
2. 不确定框架 API 时 → 必须查阅官方文档或阅读框架技能
3. 函数不存在时 → 如实告知用户，并提供替代方案
4. 参数不明确时 → 查阅文档，不要猜测

编写任何原生函数或 API 调用前：验证名称、参数以及客户端 / 服务端可用性。

---

动态文档获取

优先使用本地技能。 仅在信息缺失、过时或不确定时在线获取。

如果用户询问……	操作
原生函数	获取 https://docs.fivem.net/natives/
框架 API	阅读框架技能；不确定时获取
ox_lib	获取 https://overextended.dev/ox_lib
GTA V 资源	阅读 asset-discovery.md
通信 / Tunnel	阅读 communication.md
缓存 / 睡眠 / 广播 / cerberus 同步 / 客户端缓存 / 客户端数据播种（§2.2.1）	阅读 performance.md
/fxmind audit	阅读 audit-passes.md
新资源 / 单体架构	阅读 architecture.md + style.md
安全 / SafeEvent / 端点认证 / 输入验证	阅读 security.md
cerberus 导出 API	阅读 api.md

---

请求路由器

规则	触发条件	操作
原生检测	PascalCase 原生函数、0x...	获取 docs.fivem.net/natives
框架 API	vRP.*、QBCore.*、exports.qbx_core、ESX.*	阅读框架技能
ox_lib	lib.*	获取 overextended.dev/ox_lib
资源发现	prop / vehicle / ped 模型	阅读 asset-discovery.md
通信	Tunnel、回调、_ 前缀、同侧 TriggerEvent、响应预算	阅读 communication.md
性能	Wait(0)、循环、负载、tunnel_res、广播、缓存、客户端缓存	阅读 performance.md（§1.4–§1.6.2、§2.1–§2.2.1）
审计	/fxmind audit、重构输入	阅读 audit-passes.md（§2.3–§2.5）
架构	新资源、server.lua、重构布局	首先阅读 architecture.md §3.5–3.6
风格	注释、if/else 清理、提取 local function 还是内联	阅读 style.md（§3.11）
安全	漏洞利用、SafeEvent、端点认证、输入验证、webhook	阅读 security.md
实现 / 重构 / 新端点 / NUI	新建 func.*、RegisterNetEvent、RegisterNUICallback、重构资源	阅读 quality-gates.md
项目记忆	/fxmind learn、craft/item/loja	阅读 .fxmind/memory/<topic>.md 或建议使用 learn/query

---

编写 Lua 之前

1. 阅读 architecture.md §3.5–3.6 和 style.md §3.7–3.11
2. **任务模式：**阅读 quality-gates.md — 填写 Gate A QUALITY 计划；在进入 Gate V 之前运行自我审查循环
3. 除非有充分理由拆分，否则默认使用一个 server.lua 和一个 client.lua
4. 优先使用 Tunnel/return，避免事件往返 — communication.md §1.1

---

关键性能规则

1. **回调与事件：**不需要返回值时使用 TriggerServerEvent/TriggerClientEvent。需要返回值时才使用回调/Tunnel。
2. **动态睡眠：**绝不固定使用 Wait(0)。根据状态调整。
3. **同一环境：**直接调用函数 — 同侧绝不使用 TriggerEvent()。
4. 不要在 < 5s 的循环中进行远程调用 — 批量处理或使用增量。
5. 负载保持小巧 — 限制约为 8KB；发送增量。
6. **缓存：**对重复的 DB 查询使用 exports["cacheaside"]:Get()。
7. **大型同步：**确保 cerberus 可用时使用 SendFullSync / SendDeltaSync；否则将数据分块一次（performance.md §2.2.1）。
8. SafeEvent + 服务端验证，用于金钱/物品/XP/载具。
9. 在客户端对频繁触发的 TriggerServerEvent 使用 SetCooldown。
10. **服务端安全：**绝不信任客户端/NUI；在服务端解析派生数据（§5.2）。
11. 3 个及以上条件时使用表而非 if/else；防范 nil。
12. **合并网络调用：**使用一次带返回值的 Tunnel 调用（§1.1）。
13. **通过服务端推送播种客户端数据：**在资源启动时构建一次缓存和视图（播种 -1）；玩家加载钩子将缓存视图发送到 source；CRUD 更新一个键并发送增量。启动时绝不由客户端发送 requestSync（performance.md §2.2.1）。

---

框架技能

框架	技能
vRP Creative Network	vrp-framework
QBCore	qbcore-framework
Qbox (qbx_core)	qbox-framework
ESX Legacy	esx-framework
NUI (React + Vite)	fivem-react-nui

参见 framework-detection.md。

---

资源结构

优先采用单体结构 — architecture.md §3.5。

resource_name/
├── fxmanifest.lua
├── shared/config.lua
├── server/server.lua
└── client/client.lua

---

反模式（简要）

不要	应该
将每个功能拆分到单独的 Lua 文件中	除非有充分理由，否则采用单体结构（§3.5）
为每一行添加注释	仅注释不明显的规则（§3.7）
为单个调用位置提取 local function	直接写在处理程序／线程中（§3.11）
为修复一个 Bug 重写整个文件	尽量减少差异；保留用户认可的模式（§3.11）
伪造 LoadResourceFile 导入	使用全局或同文件辅助函数（§3.6）
通过事件往返传递返回值	使用 Tunnel／return（§1.1）
信任客户端／每次发送都重建负载	服务端鉴权 + 视图缓存（§5、§2.2）
客户端启动时请求初始数据（requestSync）	启动时由服务端推送 + 玩家加载钩子（§2.2.1）
一次 CRUD 操作后重新加载整个缓存	仅更新一个键 + 增量更新（§2.2.1）
臆造原生函数／API	先验证

完整表格：style.md §3.10–§3.11、architecture.md §3.6。

---

外部资源

• cacheaside：[email protected]:proelias7/cacheaside.git
• cerberus：[email protected]:proelias7/cerberus.git

原生函数

• https://docs.fivem.net/natives/
• 镜像：https://github.com/proelias7/fivem-natives