如果您要在 FiveM 上搭建一台角色扮演服务器，ESX Legacy 很可能是您要放下的第一块砖：它是 RP 生态中使用最广泛的经济、职业与背包框架，免费、开源，并由社区持续维护。本教程覆盖完整的安装流程，从数据库到首次启动，并附上最常见的错误及其解决办法。
首次干净安装请预留 30 到 45 分钟。
什么是 ESX Legacy？
ESX Legacy 是历史版 ESX 框架（过去称为 es_extended v1）的维护版与现代化版本。它提供了大多数 FiveM RP 服务器所依赖的公共基础：玩家账户、金钱（现金与银行）、背包、职业、公司以及权限系统。市面上绝大多数付费或免费的 RP 脚本都是为它而写的。
最知名的替代方案是 QBCore：两者在技术上都很扎实，选择主要取决于您打算使用的脚本的兼容性（见本页底部的常见问题）。
前置条件
- 一台已经能正常启动的 FiveM 服务器（
cfx-server-data基础包，或通过 txAdmin 安装）。如果还没有，请先完成FiveM 服务器的搭建，那是本教程之前的第零步。 - 一个 MySQL 或 MariaDB 数据库的访问权限。在 ElypseCloud 的 FiveM 服务器上，数据库随方案提供或作为附加选项：请在客户中心确认。
- 面板文件管理器的访问权限（ElypseCloud 使用 Pterodactyl），或 SFTP 访问权限。
- 能够编辑
server.cfg文件的基础知识。
想在不投入预算的情况下试用 ESX Legacy？免费 FiveM 方案足以完整跑完本教程，先看到框架运行起来，再换到适合真实玩家规模的方案。
第 1 步：准备数据库
请新建一个专用数据库，不要复用已经服务于其他项目的数据库。请准确记录：
- 数据库名称
- 用户名及其密码
- 主机地址（通常是
localhost，如果数据库是共享的则为内网地址）
这三项信息将在第 4 步用到。
第 2 步：安装 oxmysql
ESX Legacy 需要一个异步 MySQL 连接器才能与数据库通信。目前 FiveM 生态的标准是 oxmysql。较旧的 mysql-async / ghmattimysql 在部分环境下仍可用，但 ESX Legacy 官方文档现在推荐的是 oxmysql。阅读本文时请同时查阅框架官方文档，FiveM 生态变化很快。
- 从官方仓库下载最新的 oxmysql 发布版。
- 将文件夹放到
resources/[core]/oxmysql（前缀[core]只是归类约定，并非技术要求）。 - 在
server.cfg中，于任何加载 ESX 的行之前加入：
ensure oxmysql第 3 步：下载 es_extended 与 ESX 资源
从 ESX Legacy 官方仓库获取 es_extended（框架核心），以及您需要的附加资源：spawnmanager、esx_menu_default、esx_context 等。具体清单取决于版本以及您准备在其上安装的脚本。
请将每个资源放进 resources/[esx]/ 下各自独立的文件夹。
第 4 步：配置 server.cfg
您的 server.cfg 必须按以下顺序加载：
ensure oxmysql
ensure es_extended
ensure spawnmanager
ensure esx_menu_default
ensure esx_menu_dialog
ensure esx_menu_list然后加入数据库连接字符串，替换为第 1 步中您自己的真实信息：
set mysql_connection_string "mysql://用户名:密码@localhost/数据库名?charset=utf8mb4"加载顺序很关键。oxmysql 必须始终早于 es_extended 启动，否则 ESX 在启动时找不到数据库连接并崩溃。
第 5 步：导入 SQL 结构
ESX Legacy 仓库提供了一个包含基础结构（玩家表、公司表等）的 .sql 文件。请根据面板提供的工具，通过 phpMyAdmin、Adminer 或命令行将其导入数据库。
第 6 步：启动并测试
在面板中重启服务器，并观察启动过程中的控制台输出。进入游戏后，您应该以一个空白角色出现在出生点。如果 ESX 菜单能够打开（大多数配置下默认是 F2），说明安装成功。
常见错误
「oxmysql wasn't ready before a resource was started」
MySQL 连接器还没来得及初始化，es_extended 就尝试连接了。请检查 server.cfg 中的顺序（oxmysql 在前），以及连接字符串是否正确。
数据库连接错误（「Access denied」、「Unknown database」）
请检查 mysql_connection_string 中的用户名、密码和数据库名，并确认该 MySQL 用户确实拥有这个数据库的权限。
启动时出现「Could not find resource」
server.cfg 中列出的某个资源没有放在 resources/ 下正确的位置，或者文件夹名称与 server.cfg 中的写法不完全一致，在部分系统上这是区分大小写的。
角色不出生 / 一直黑屏
请确认 spawnmanager 在 es_extended 之后加载，并先在控制台查找更具体的 Lua 或 JS 报错，再继续排查。
接下来做什么？
ESX Legacy 就位之后，下一步取决于您的项目：职业脚本、进阶背包、公司系统。抛开框架本身，基础设施上有两点值得注意：脚本数量增长后的可用内存，以及高负载下数据库连接的质量。大多数 RP 服务器开始卡顿的原因在这里，而不在 ESX 内部。如果您在当前服务商那里已经遇到这种情况，我们专门写了一个页面。