Arch Linux 安装 UE 二进制版，包括 Fab、构建、clangd 与 CodeLLDB

Yoimiya2026/10/19大约 16 分钟

本文记录在 Arch Linux 上使用 Unreal Engine 官方预编译版的过程：下载和解压引擎、安装 Fab 插件、构建 C++ 项目、使用 RunUAT 打包，以及配置 VS Code 的 clangd 和 CodeLLDB。

使用预编译引擎时，日常开发主要编译自己的项目和源码插件。阅读安装包附带的引擎源码、调试现成编辑器，都可以先从这套环境开始。

参考

一、环境与工具分工

这次使用的环境：

项目	版本或位置
系统	Arch Linux x86_64，Wayland 桌面
显卡	Intel 核显 + NVIDIA RTX 4050 Laptop GPU
UE	官方 Linux 预编译版 5.8.3
Fab	Linux 插件 0.0.13，下载包标注 UE 5.8.0
引擎目录	`~/Applications/UnrealEngine-5.8.3`
C++ 项目	`~/Documents/Unreal Projects/LinuxTest`
UE 自带编译器	v26，Clang 20.1.8
UE 自带 .NET	`Engine/Binaries/ThirdParty/DotNet/10.0/linux-x64`
系统 clangd	23.1.3，由 Arch 的 `clang` 包提供
VS Code 调试扩展	CodeLLDB 1.12.3，`vadimcn.vscode-lldb`

几个名字容易混淆：

工具	负责什么
UE Editor	关卡、蓝图、资源编辑与 Play In Editor 测试
UnrealBuildTool，简称 UBT	管理目标、模块依赖，调用代码生成工具和编译器
`Build.sh`	调用 UBT，构建或清理具体目标
Unreal Automation Tool，简称 UAT	自动化构建、Cook、暂存、打包等流程
`RunUAT.sh`	Linux 上的 UAT 入口
clangd	VS Code 的 C/C++ 补全、诊断、跳转和索引
CodeLLDB	VS Code 的原生代码调试，包括断点、调用栈和变量查看

系统 clangd 与 UE 编译器分别使用自己的版本。 安装 Arch 的 clang 包是为了获得语言服务器；项目的实际编译仍交给 UBT 和引擎自带的 Clang 20.1.8。

二、下载 UE 二进制版和 Fab 插件

本次下载的文件：

~/Downloads/Linux_Unreal_Engine_5.8.3.zip
~/Downloads/Linux_Fab_5.8.0_0.0.13.zip

下载页需要 Epic 账号登录。具体可用文件名以登录后的列表为准，其他版本要同时调整本文的路径和工具链名称。

UE 压缩包约 37.1 GiB，包内文件的未压缩大小约 71.7 GiB。后续项目、中间文件、着色器缓存和打包输出还会继续占用空间。

三、安装 Arch 工具并检查运行环境

安装系统 clangd、解压和 Vulkan 检查工具：

sudo pacman -Syu clang 7zip vulkan-tools

这里使用 pacman -Syu clang 的完整升级方式，同时安装另外两个工具。

确认 clangd：

clangd --version
pacman -Qo /usr/bin/clangd

本机的 /usr/bin/clangd 属于 clang 包。之后 VS Code 使用它提供语言服务。

检查磁盘、Vulkan 和 NVIDIA 驱动：

df -h "$HOME/Downloads"
vulkaninfo --summary
nvidia-smi

nvidia-smi 只适用于 NVIDIA。本机已安装 nvidia-open、nvidia-utils 和 vulkan-icd-loader；其他显卡应配置各自对应的驱动与 Vulkan 实现。

这份 UE 安装包已经带有编译工具链和 .NET SDK，所以通常无需再为项目构建单独安装系统 dotnet-sdk、lld 或 cmake。第三方插件如果有额外构建依赖，再根据插件说明处理。

四、解压引擎和 Fab

4.1 约定目录变量

下文的终端命令使用这些变量。新开终端后需要重新设置：

UE_ROOT="$HOME/Applications/UnrealEngine-5.8.3"
PROJECT_DIR="$HOME/Documents/Unreal Projects/LinuxTest"
UE_PROJECT="$PROJECT_DIR/LinuxTest.uproject"
UE_CXX="$UE_ROOT/Engine/Extras/ThirdPartyNotUE/SDKs/HostLinux/Linux_x64/v26_clang-20.1.8-rockylinux8/x86_64-unknown-linux-gnu/bin/clang++"

项目路径含有空格，传给命令时始终使用双引号。

4.2 解压引擎

mkdir -p "$UE_ROOT"

7z x "$HOME/Downloads/Linux_Unreal_Engine_5.8.3.zip" \
  "-o$UE_ROOT"

这个包的顶层已经包含 Engine、Templates 等目录。解压后编辑器应位于：

~/Applications/UnrealEngine-5.8.3/Engine/Binaries/Linux/UnrealEditor

检查执行权限：

test -x "$UE_ROOT/Engine/Binaries/Linux/UnrealEditor" \
  && echo "UnrealEditor is executable"

本次使用 7-Zip 解压后，UnrealEditor 和 ShaderCompileWorker 都保留了 755 权限，不需要递归修改整个引擎目录的权限。

安装在自己的家目录下，后续项目构建和缓存写入也更方便。

4.3 解压 Fab 插件

先查看压缩包结构：

7z l "$HOME/Downloads/Linux_Fab_5.8.0_0.0.13.zip"

本次插件包包含：

Engine/Plugins/Fab/Fab.uplugin
Engine/Plugins/Fab/Binaries/Linux/UnrealEditor.modules
Engine/Plugins/Fab/Binaries/Linux/libUnrealEditor-Fab.so

7z x "$HOME/Downloads/Linux_Fab_5.8.0_0.0.13.zip" \
  "-o$UE_ROOT"

最后应得到：

~/Applications/UnrealEngine-5.8.3/Engine/Plugins/Fab/Fab.uplugin

如果把这个带有 Engine/Plugins 层级的压缩包直接解到 Engine/Plugins，就会多套一层错误目录。

4.4 核对插件与引擎的 BuildId

插件下载包标注 5.8.0，而引擎是 5.8.3。除了版本号，还可以核对两个模块清单的 BuildId：

python - "$UE_ROOT" <<'PY'
from pathlib import Path
import json
import sys

root = Path(sys.argv[1])
engine_file = root / "Engine/Binaries/Linux/UnrealEditor.modules"
plugin_file = root / "Engine/Plugins/Fab/Binaries/Linux/UnrealEditor.modules"

engine_id = json.loads(engine_file.read_text())["BuildId"]
plugin_id = json.loads(plugin_file.read_text())["BuildId"]

print("Engine BuildId:", engine_id)
print("Fab BuildId:   ", plugin_id)

if engine_id != plugin_id:
    raise SystemExit("BuildId 不一致，请检查插件是否匹配当前引擎。")
PY

本次两个值均为 55116800，插件包里的 190 个文件也通过了大小和 CRC 校验。

五、启动编辑器并使用 Fab

5.1 Wayland 桌面下使用 XWayland

本机采用双显卡，以下命令使用 XWayland，并通过 NVIDIA PRIME 配置让独显优先参与设备选择：

SDL_VIDEODRIVER=x11 \
__NV_PRIME_RENDER_OFFLOAD=1 \
__VK_LAYER_NV_optimus=NVIDIA_only \
"$UE_ROOT/Engine/Binaries/Linux/UnrealEditor"

NVIDIA 的两个变量用于 PRIME render offload。单显卡或其他厂商显卡可以按自己的环境调整。NVIDIA PRIME 文档

5.2 尝试原生 Wayland

把 SDL 后端改为 wayland：

SDL_VIDEODRIVER=wayland \
__NV_PRIME_RENDER_OFFLOAD=1 \
__VK_LAYER_NV_optimus=NVIDIA_only \
"$UE_ROOT/Engine/Binaries/Linux/UnrealEditor"

Epic 的 SDL3 说明仍列出了原生 Wayland 的鼠标和焦点问题。日常配置默认使用 XWayland，原生 Wayland 留作单独测试。Epic SDL3 说明

5.3 启用 Fab 并添加资源

在 Edit → Plugins 中搜索 Fab，确认启用，按提示重启编辑器。
打开 Window → Fab，或者 Content Drawer 中的 Fab 按钮。
登录 Epic 账号。
将需要的资源加入 My Library，在库中点击资源卡片上的 ＋ 添加到当前项目。

Fab 插件在这份包中默认启用。UE 格式资源通常通过编辑器集成或 Launcher 导入；FBX、GLB、贴图等通用格式，则可以在网页下载相应文件后手动导入。Fab 下载说明

代码插件还需要确认 UE 版本和 Linux 支持情况，只有 Win64 二进制的插件无法直接在 Linux 编辑器中加载。

六、创建 C++ 项目与常用构建命令

在编辑器中创建名为 LinuxTest 的 C++ 项目，本文使用的位置是：

/home/yoimiya/Documents/Unreal Projects/LinuxTest/LinuxTest.uproject

项目包含 Source/LinuxTestEditor.Target.cs 时，对应的编辑器目标名就是 LinuxTestEditor。换成其他项目后，应同时修改下文目标名与 .uproject 路径。

6.1 构建日常使用的 Editor 目标

"$UE_ROOT/Engine/Build/BatchFiles/Linux/Build.sh" \
  LinuxTestEditor Linux Development \
  "-Project=$UE_PROJECT" -WaitMutex

三个主要参数依次是目标、平台和配置。-WaitMutex 用于等待其他 UBT 构建实例结束。

这会构建编辑器需要加载的项目模块，例如：

Binaries/Linux/libUnrealEditor-LinuxTest.so

UBT 也会按需运行 UnrealHeaderTool，生成反射相关文件。初次构建之后，只改少量源码时通常走增量构建。

修改反射声明、类结构或构造逻辑时，可以采用“保存资源并关闭编辑器 → 构建 → 重新打开项目”的流程。

6.2 打开已经构建的项目

SDL_VIDEODRIVER=x11 \
__NV_PRIME_RENDER_OFFLOAD=1 \
__VK_LAYER_NV_optimus=NVIDIA_only \
"$UE_ROOT/Engine/Binaries/Linux/UnrealEditor" "$UE_PROJECT"

6.3 DebugGame 与 Game 目标

需要更方便地调试自己的 C++ 逻辑时，可以构建 Editor 的 DebugGame 配置：

"$UE_ROOT/Engine/Build/BatchFiles/Linux/Build.sh" \
  LinuxTestEditor Linux DebugGame \
  "-Project=$UE_PROJECT" -WaitMutex

启动时也要选择匹配 DebugGame 的启动配置。本文后面的完整工作区以日常使用的 Development Editor 为默认配置。

构建独立游戏目标：

"$UE_ROOT/Engine/Build/BatchFiles/Linux/Build.sh" \
  LinuxTest Linux Development \
  "-Project=$UE_PROJECT" -WaitMutex

Game 目标的代码构建与资源打包是不同阶段。需要可分发目录时，继续使用 RunUAT 执行 Cook、Stage 和打包流程。

6.4 清理项目目标

确实需要清理项目构建产物时：

"$UE_ROOT/Engine/Build/BatchFiles/Linux/Build.sh" \
  LinuxTestEditor Linux Development \
  "-Project=$UE_PROJECT" -WaitMutex -clean

日常直接增量构建即可，无需每次先清理。

七、使用 RunUAT 构建和打包

Linux 上使用：

Engine/Build/BatchFiles/RunUAT.sh

Windows 对应的是 RunUAT.bat。常用的 BuildCookRun 把多个阶段串起来：

阶段	作用
Build	编译目标平台的项目代码和插件
Cook	将资源转换成目标平台可用的数据
Stage	把程序、资源和依赖收集到暂存目录
Pak	将资源组织成 Pak 容器，具体输出也受项目设置影响
Package	执行目标平台的打包步骤
Archive	将构建结果归档到指定目录

例如，生成 Linux Development 包：

"$UE_ROOT/Engine/Build/BatchFiles/RunUAT.sh" BuildCookRun \
  "-project=$UE_PROJECT" \
  -nop4 \
  -platform=Linux \
  -clientconfig=Development \
  -build -cook -stage -pak -package -archive \
  "-archivedirectory=$HOME/Builds/LinuxTest-Linux" \
  -utf8output

准备发布时，可将 -clientconfig=Development 改成 -clientconfig=Shipping。

常用参数：

参数	含义
`-project=...`	项目文件的完整路径
`-platform=Linux`	目标平台
`-clientconfig=Development`	游戏目标的构建配置
`-nop4`	不使用 Perforce 集成
`-archivedirectory=...`	归档输出目录
`-utf8output`	使用 UTF-8 输出日志

这些是常用命令模板。具体地图、插件和打包选项，应先在项目的 Packaging 设置里配置。Epic 构建流程说明

-platform 也受宿主系统和工具链支持限制。Windows 可以安装官方 Linux 交叉编译 SDK；本机这份 Linux UE 没有开箱即用的 Windows 项目打包流程。要生成 Windows 版本，可以把同一份项目交给 Windows 构建环境。

八、配置 VS Code 和 clangd

8.1 安装扩展

安装 clangd 和 CodeLLDB：

code --install-extension llvm-vs-code-extensions.vscode-clangd
code --install-extension vadimcn.vscode-lldb

需要编辑 .Build.cs、.Target.cs 等构建规则时，还可以安装 C# 扩展：

code --install-extension ms-dotnettools.csharp

本文选择：

clangd 提供 C/C++ 语言服务。
CodeLLDB 提供 F5 调试。
C# 扩展辅助阅读和编辑构建规则。

这套组合不要求安装微软的 ms-vscode.cpptools。如果已经安装了 cpptools，选择 clangd 作为语言服务时，可以关闭 cpptools 的 IntelliSense，避免两套诊断同时工作。

8.2 生成 VS Code 工作区

在 UE 的 Edit → Editor Preferences → General → Source Code 中选择 Visual Studio Code。

也可以直接用安装包里的脚本生成工作区：

"$UE_ROOT/Engine/Build/BatchFiles/Linux/GenerateProjectFiles.sh" \
  "-project=$UE_PROJECT" -game -engine -vscode

code "$PROJECT_DIR/LinuxTest.code-workspace"

二进制版的脚本位于 Engine/Build/BatchFiles/Linux。

生成器默认推荐 cpptools，并写入 .vscode/c_cpp_properties.json。但 clangd 不会读取这个文件。

本次遇到的日志就是：

Failed to find compilation database
'CoreMinimal.h' file not found

8.3 用 UBT 生成真正的编译数据库

先完成一次 LinuxTestEditor Linux Development 正常构建，确保反射头、模块定义和其他生成文件已经存在，再运行：

mkdir -p "$PROJECT_DIR/.vscode"

"$UE_ROOT/Engine/Build/BatchFiles/Linux/Build.sh" \
  -Mode=GenerateClangDatabase \
  LinuxTestEditor Linux Development \
  "-Project=$UE_PROJECT" \
  "-OutputDir=$PROJECT_DIR/.vscode" \
  -NoExecCodeGenActions

输出文件是：

LinuxTest/.vscode/compile_commands.json

这一步生成编译信息，不会把整个引擎重新编译一遍。-NoExecCodeGenActions 跳过该模式中的额外代码生成动作，因此前面正常构建生成的文件仍然重要。

UBT 生成的数据库包含编译器、响应文件、宏定义、标准库与 sysroot 等真实参数。

本次数据库包含 25 条项目源码和生成代码记录；数量会随项目和构建方式变化。

8.4 在项目根目录放一个相对链接

首次配置、且根目录尚无 compile_commands.json 时：

ln -s .vscode/compile_commands.json \
  "$PROJECT_DIR/compile_commands.json"

得到：

LinuxTest/compile_commands.json -> .vscode/compile_commands.json

已有数据库或链接时，先确认它指向哪里，不要直接覆盖。

这个链接便于 clangd 和其他 Clang 工具从源码的父目录自动发现数据库。工作区配置还会显式指定数据库目录。clangd 编译数据库说明

8.5 指定 UE 编译器供 clangd 查询

后面的完整配置包含：

clangd.path：使用 /usr/bin/clangd。
--compile-commands-dir=...：指向项目 .vscode 目录。
--query-driver=.../clang++：允许 clangd 查询 UE 编译器的目标和系统头文件目录。
--background-index：开启后台索引。

这里的 --query-driver 指向 UE_CXX 对应的那个实际可执行文件，不是系统的 /usr/bin/clang++。clangd 系统头文件说明

可以先在终端独立验证：

clangd \
  "--check=$PROJECT_DIR/Source/LinuxTest/LinuxTest.cpp" \
  "--compile-commands-dir=$PROJECT_DIR/.vscode" \
  "--query-driver=$UE_CXX"

本次检查 LinuxTest.cpp、LinuxTestCharacter.cpp 和引擎 CoreMinimal.h 时，解析均得到 0 errors。

项目数据库会覆盖项目源码及它们引用的引擎头文件。预编译引擎下，这份数据库不等于整套 UE 私有 .cpp 的完整编译数据库，因此全引擎跨文件引用和实现索引仍有范围限制。

九、配置 CodeLLDB 与引擎源码映射

9.1 扩展自带的后端

安装 vadimcn.vscode-lldb 后，平台包可能已经包含原生组件；缺少时，扩展会自动获取对应的平台包。

本机最终得到：

~/.vscode/extensions/vadimcn.vscode-lldb-1.12.3/
├── platform.ok
├── adapter/codelldb
└── lldb/
    ├── bin/lldb
    └── lib/liblldb.so

本次使用扩展自己的后端，没有额外安装 AUR 的 codelldb。

语言服务和调试器相互独立：clangd 可以与 GDB 配合使用；本文采用 CodeLLDB，是为了在 VS Code 中提供断点和 F5 调试界面。

9.2 将启动类型改成 lldb

UE 默认生成的原生调试配置通常是：

{
  "type": "cppdbg"
}

这个类型由 cpptools 提供。使用 CodeLLDB 时需要改为：

{
  "type": "lldb",
  "request": "launch"
}

转换时同时移除 cpptools 的 visualizerFile、showDisplayString 等专用字段，改用 LLDB 的 UE 类型格式化脚本。

9.3 加载 UE 类型格式化脚本

安装包中提供了：

Engine/Extras/LLDBDataFormatters/UEDataFormatters_2ByteChars.py

工作区会在初始化时执行：

settings set target.inline-breakpoint-strategy always
command script import "/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Extras/LLDBDataFormatters/UEDataFormatters_2ByteChars.py"

脚本为 FString、FName、TArray 等 UE 类型注册 LLDB 格式化支持。

9.4 将官方构建机路径映射到本机源码

预编译编辑器的调试符号里可能记录了 Epic 构建机上的路径。本次读到的编译目录包括：

/mnt/horde/++UE5/Sync/Engine/Source

因此配置映射：

{
  "lldb.launch.sourceMap": {
    "/mnt/horde/++UE5/Sync": "/home/yoimiya/Applications/UnrealEngine-5.8.3"
  }
}

这样调试器可以将构建机上的引擎源码路径关联到本机安装目录。

可以用 readelf 查看调试符号中的编译目录：

readelf --debug-dump=info --dwarf-depth=1 \
  "$UE_ROOT/Engine/Binaries/Linux/UnrealEditor.debug" \
  | sed -n '/DW_AT_comp_dir/p'

CodeLLDB 的 lldb.launch.* 设置会作为各启动项的默认配置，与具体启动项合并。因此可以把环境变量和源码映射集中放在工作区里，再让 Wayland 启动项只覆盖 SDL 后端。CodeLLDB 配置说明

十、完整的 LinuxTest.code-workspace 示例

以下是从本次实际工作区提取的精简完整配置，包含两个启动项和两个任务。保留现有个人配置时，可以只合并需要的字段；整份替换前先备份原工作区。

JSON 中的绝对路径要按实际环境修改。它们不会自动展开前文终端里的 $UE_ROOT、$UE_PROJECT 等 shell 变量。

LinuxTest.code-workspace

{
  "folders": [
    {
      "name": "LinuxTest",
      "path": "."
    },
    {
      "name": "UE5",
      "path": "/home/yoimiya/Applications/UnrealEngine-5.8.3"
    }
  ],
  "settings": {
    "clangd.path": "/usr/bin/clangd",
    "clangd.arguments": [
      "--compile-commands-dir=/home/yoimiya/Documents/Unreal Projects/LinuxTest/.vscode",
      "--query-driver=/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Extras/ThirdPartyNotUE/SDKs/HostLinux/Linux_x64/v26_clang-20.1.8-rockylinux8/x86_64-unknown-linux-gnu/bin/clang++",
      "--background-index"
    ],
    "terminal.integrated.env.linux": {
      "PATH": "/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Binaries/ThirdParty/DotNet/10.0/linux-x64:${env:PATH}",
      "DOTNET_ROOT": "/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Binaries/ThirdParty/DotNet/10.0/linux-x64",
      "DOTNET_HOST_PATH": "/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Binaries/ThirdParty/DotNet/10.0/linux-x64/dotnet",
      "DOTNET_MULTILEVEL_LOOKUP": "0",
      "DOTNET_ROLL_FORWARD": "LatestMajor"
    },
    "lldb.launch.initCommands": [
      "settings set target.inline-breakpoint-strategy always",
      "command script import \"/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Extras/LLDBDataFormatters/UEDataFormatters_2ByteChars.py\""
    ],
    "lldb.launch.sourceMap": {
      "/mnt/horde/++UE5/Sync": "/home/yoimiya/Applications/UnrealEngine-5.8.3"
    },
    "lldb.launch.env": {
      "SDL_VIDEODRIVER": "x11",
      "__NV_PRIME_RENDER_OFFLOAD": "1",
      "__VK_LAYER_NV_optimus": "NVIDIA_only"
    }
  },
  "extensions": {
    "recommendations": [
      "llvm-vs-code-extensions.vscode-clangd",
      "ms-dotnettools.csharp",
      "vadimcn.vscode-lldb"
    ]
  },
  "tasks": {
    "version": "2.0.0",
    "tasks": [
      {
        "label": "LinuxTestEditor Linux Development Build",
        "group": "build",
        "command": "/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Build/BatchFiles/Linux/Build.sh",
        "args": [
          "LinuxTestEditor",
          "Linux",
          "Development",
          "-Project=/home/yoimiya/Documents/Unreal Projects/LinuxTest/LinuxTest.uproject",
          "-WaitMutex"
        ],
        "problemMatcher": "$gcc",
        "type": "process",
        "options": {
          "cwd": "/home/yoimiya/Applications/UnrealEngine-5.8.3"
        }
      },
      {
        "label": "Refresh clangd compilation database",
        "type": "process",
        "command": "/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Build/BatchFiles/Linux/Build.sh",
        "args": [
          "-Mode=GenerateClangDatabase",
          "LinuxTestEditor",
          "Linux",
          "Development",
          "-Project=/home/yoimiya/Documents/Unreal Projects/LinuxTest/LinuxTest.uproject",
          "-OutputDir=/home/yoimiya/Documents/Unreal Projects/LinuxTest/.vscode",
          "-NoExecCodeGenActions"
        ],
        "options": {
          "cwd": "/home/yoimiya/Applications/UnrealEngine-5.8.3"
        },
        "problemMatcher": []
      }
    ]
  },
  "launch": {
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Launch LinuxTestEditor (Development)",
        "request": "launch",
        "program": "/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Binaries/Linux/UnrealEditor",
        "preLaunchTask": "LinuxTestEditor Linux Development Build",
        "args": [
          "/home/yoimiya/Documents/Unreal Projects/LinuxTest/LinuxTest.uproject"
        ],
        "cwd": "/home/yoimiya/Applications/UnrealEngine-5.8.3",
        "type": "lldb",
        "stopOnEntry": false
      },
      {
        "name": "Launch LinuxTestEditor (Development, Wayland)",
        "request": "launch",
        "program": "/home/yoimiya/Applications/UnrealEngine-5.8.3/Engine/Binaries/Linux/UnrealEditor",
        "preLaunchTask": "LinuxTestEditor Linux Development Build",
        "args": [
          "/home/yoimiya/Documents/Unreal Projects/LinuxTest/LinuxTest.uproject"
        ],
        "cwd": "/home/yoimiya/Applications/UnrealEngine-5.8.3",
        "type": "lldb",
        "stopOnEntry": false,
        "env": {
          "SDL_VIDEODRIVER": "wayland"
        }
      }
    ]
  }
}

其中：

LinuxTest 是项目目录，UE5 是引擎目录。
构建任务使用 type: process，路径和参数分别传递，项目目录含空格也能正确处理。
preLaunchTask 与构建任务名称完全一致。
program 指向引擎的 UnrealEditor，args 则传入具体项目。
默认 SDL 后端是 x11；Wayland 启动项覆盖成 wayland，仍继承 NVIDIA 环境变量。
terminal.integrated.env.linux 让集成终端可以直接找到 UE 的 .NET。Build.sh 自己也会准备其所需的 .NET 环境。
刷新数据库任务对应前面的 GenerateClangDatabase 命令。

这份配置的 F5 启动项是 Development Editor。它不会启动 LinuxTest 的独立游戏目标，也不依赖系统里另装一份 LLDB。

十一、点击绿色三角形启动 Editor

保存工作区后：

按 Ctrl+Shift+P，执行 Developer: Reload Window。
打开一个项目 .cpp，等待 clangd 索引。
按 Ctrl+Shift+D，打开“运行和调试”。
在顶部下拉框选择 Launch LinuxTestEditor (Development)。
点击下拉框旁边的绿色三角形，或者按 F5。

预期流程：

构建 LinuxTestEditor Linux Development
  → CodeLLDB 加载 UnrealEditor
  → 传入 LinuxTest.uproject
  → 打开项目编辑器

要单独试原生 Wayland，选择 Launch LinuxTestEditor (Development, Wayland)。

启动后，在项目 C++ 中下断点，再通过 Play In Editor 触发对应逻辑。需要观察引擎主循环时，也可以添加函数断点 FEngineLoop::Tick；它每帧都会执行，适合短时间观察调用栈。

日常修改后的操作

修改普通 C++ 实现后，构建项目并重新运行。
新增反射类时，先正常构建，确保对应 .generated.h 已生成。
新增源码、调整模块或插件后，在“终端 → 运行任务”中执行 Refresh clangd compilation database。
需要完整重新生成 VS Code 工程时再运行 GenerateProjectFiles.sh，并保留自定义 clangd、CodeLLDB 设置。

工作区重新生成

UE 的工程生成脚本可能覆盖 .code-workspace。只想刷新 clangd 的编译信息时，使用单独的数据库刷新任务，可以保留当前工作区里的自定义调试设置。

十二、常见问题与本次验证范围

现象	检查位置
`CoreMinimal.h` 找不到	clangd 是否加载了正确的 `compile_commands.json`
生成头文件找不到	是否先正常构建了 Editor 目标，数据库是否仍对应当前模块
提示不支持 `cppdbg`	当前选中的是否还是旧启动项，是否已经改成 CodeLLDB 的 `lldb`
点击运行却没有进入编辑器	是否选择了 `LinuxTestEditor` 启动项，`program` 和 `args` 是否正确
引擎断点无法定位本机源码	`.debug` 文件、源码版本、`sourceMap` 是否匹配
原生 Wayland 的点击或焦点异常	切回 `SDL_VIDEODRIVER=x11` 的启动项验证

本次已经完成的检查：

检查	结果
UE 解压与执行权限抽样	通过
Fab 190 个文件的大小与 CRC 校验	通过
Fab 与引擎模块 BuildId	均为 `55116800`
`LinuxTestEditor Linux Development` 构建	成功
两个项目 `.cpp` 与引擎 `CoreMinimal.h` 的 clangd 解析	`0 errors`
CodeLLDB 原生后端与 UE 类型格式化脚本加载	通过
`FEngineLoop::Tick` 符号与本机源码行断点解析	通过
VS Code 图形界面中 F5 启动 Editor	配置已就绪，实际窗口启动结果以桌面端验证为准
RunUAT 完整 Cook、Package、Archive	本文提供命令模板，未执行实测

安装包里的 Engine/Source 已经包含大量引擎 .cpp，并附带对应的调试符号。后续学习主循环、对象生命周期、任务系统或 RDG 时，可以先使用这份预编译引擎阅读和调试，再按具体实验决定是否需要完整源码构建。