FiveM TypeScript 开发：带类型的现代脚本

为什么 FiveM 选择 TypeScript？

TypeScript 为 FiveM 开发带来静态类型检查、现代 JavaScript 特性及更优的 IDE 支持。虽然 Lua 仍是标准脚本语言，TypeScript 编译成 JavaScript 可通过 JavaScript 运行时在 FiveM 原生运行。类型安全在编译时捕获可能导致服务器运行时崩溃的错误，自动补全显著加快开发速度，接口使代码自带文档。对于多开发者复杂项目，TypeScript 降低协调成本，重构更安全。

使用 fivem-ts-boilerplate 进行项目设置

启动TypeScript FiveM项目最快的方法是使用社区fivem-ts-boilerplate。克隆模板仓库，运行 npm install 设置依赖项，您将拥有一个可用的项目结构，包含独立的客户端、服务器和共享源目录。该样板包含一个webpack配置，将TypeScript编译为兼容FiveM的JavaScript包，并附带FiveM原生函数、citizen函数和常见框架API的类型定义。使用 npm run build 并且输出直接进入资源文件夹。

类型定义与原生函数

该 @citizenfx/client 和 @citizenfx/server type 包提供所有 FiveM 原生函数和 API 调用的 TypeScript 定义。这些定义支持函数如的自动补全 GetEntityCoords, SetEntityHealth，和 RegisterCommand，在编码时显示参数类型和返回值。针对 QBCore 或 ESX 等框架特定 API，您可以创建或安装额外的类型定义文件，涵盖框架导出和事件。这使您的 IDE 成为整个 FiveM API 的交互式文档浏览器。

客户端与服务器架构

将您的TypeScript项目结构清晰地分离客户端和服务器端代码。使用shared目录存放双方都需要的接口、枚举和实用函数。在共享类型中定义事件载荷接口，以便编译器验证客户端和服务器对数据结构的一致性。从抽象底层框架的服务层导入框架包装器，使您的业务逻辑可在QBCore、ESX和独立设置之间移植。此架构使您的代码库模块化且易于测试。

FiveM 中的 TypeScript 调试

调试编译后的代码具有挑战性，因为执行的 JavaScript 与你的 TypeScript 源代码不同。请在 webpack 配置中启用源映射，以便错误堆栈跟踪引用你的原始 TypeScript 文件。使用 console.log 转发到FiveM服务器控制台以进行服务器端调试的语句。对于客户端调试，可通过F8访问的NUI开发者工具检查JavaScript执行。考虑添加包含时间戳、日志级别和源文件引用的结构化日志工具，以便通过编译输出更容易追踪问题。

与 Lua 的迁移与共存

您无需一次性将整个服务器转换为 TypeScript。TypeScript 资源与 Lua 资源完美共存，因为它们通过相同的事件和导出系统通信。开始时用 TypeScript 构建新功能，同时维护现有 Lua 脚本。从 TypeScript 调用 Lua 导出时，创建描述预期函数签名的类型声明。随着对 TypeScript 工作流程的信心增加，逐步迁移关键系统。这种渐进式方法让您的团队在保持服务器稳定、避免风险性全面重写的同时学习 TypeScript。