QBCore 服务器快速搭建入门

面向第一次搭建 FiveM 角色扮演服务器的新手，假设你已经有一台 Linux 或 Windows 服务器。

前置条件

系统：Windows Server 2019+ / Ubuntu 22.04+ / Debian 12+
数据库：MySQL 5.7+ 或 MariaDB 10.4+
端口：TCP/UDP 30120（客户端连接）+ TCP 40120（txAdmin 面板）
FiveM license key：到 keymaster.fivem.net 免费申请

一、安装 FXServer

Linux (推荐)

mkdir -p /opt/fxserver && cd /opt/fxserver
wget https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/<最新版>/fx.tar.xz
tar -xf fx.tar.xz

Windows

直接下载 ZIP 解压到 C:\FXServer\server 即可。

二、配置 txAdmin

首次启动 FXServer 会弹出 txAdmin 配置向导：

./run.sh +set serverProfile default

按向导填入：

License key
MySQL 连接字符串 mysql://user:pass@host:3306/dbname?charset=utf8mb4
服务器名称、最大玩家数

三、拉取 QBCore 资源

进入 resources 目录：

cd /opt/fxserver/txData/default/resources
git clone https://github.com/qbcore-framework/qb-core.git [qb]/qb-core
git clone https://github.com/qbcore-framework/qb-multicharacter.git [qb]/qb-multicharacter
git clone https://github.com/qbcore-framework/qb-spawn.git [qb]/qb-spawn

然后在 server.cfg 里添加：

ensure qb-core
ensure qb-multicharacter
ensure qb-spawn
# ... 其他 qb-* 脚本

四、常见坑

启动时报 "database is not available"

检查 MySQL 是否允许远程连接，以及 oxmysql 的连接字符串是否正确（注意字符集必须带 charset=utf8mb4）。

进服后无法生成角色

QBCore 需要 qb-multicharacter 和 qb-spawn 配合。确认两者都在 server.cfg 里 ensure。

中文乱码

fxmanifest.lua 需要 UTF-8 BOM 开头，或者在文件第一行加：

-- @charset=utf-8

数据库所有表的字符集设置为 utf8mb4unicodeci。

五、下一步

安装 ox_inventory 替代默认物品栏
添加 qb-policejob 启用警务职业
接入 pma-voice 做语音