1. 為什么我不再用 Rider 和 Visual Studio 寫 UE5 項(xiàng)目先說(shuō)結(jié)論UE5 項(xiàng)目用 VS Code 開(kāi)發(fā)不是能不能的問(wèn)題而是怎么配才不折騰的問(wèn)題。我從 UE4.26 時(shí)代就開(kāi)始嘗試把 UE 的開(kāi)發(fā)環(huán)境從 Visual Studio 遷移到 VS Code中間踩過(guò)的坑包括 IntelliSense 瘋狂報(bào)紅、編譯任務(wù)找不到 UBT、調(diào)試器附加不上、Live Coding 控制臺(tái)沒(méi)輸出等等。到現(xiàn)在 UE5.3 之后的版本這套流程已經(jīng)相當(dāng)穩(wěn)定了日常寫 C 和藍(lán)圖混合項(xiàng)目完全夠用。這篇文章面向三類人一是機(jī)器配置一般、開(kāi) Visual Studio 就卡到懷疑人生的開(kāi)發(fā)者二是習(xí)慣了 VS Code 生態(tài)、不想為了 UE 單獨(dú)切換編輯器的人三是想搞清楚 UE5 構(gòu)建系統(tǒng)底層邏輯、不想被 IDE 黑盒綁架的人。我會(huì)從環(huán)境準(zhǔn)備、插件選型、編譯任務(wù)配置、調(diào)試器接入、常見(jiàn)報(bào)錯(cuò)排查幾個(gè)維度把整套流程拆開(kāi)講清楚每一步都告訴你為什么這么做而不是丟一堆配置文件讓你抄。需要提前說(shuō)明的是UE5 的 C 開(kāi)發(fā)本質(zhì)上依賴的是UnrealBuildToolUBT和UnrealHeaderToolUHT這套命令行工具鏈IDE 只是外殼。Visual Studio 之所以開(kāi)箱即用是因?yàn)?Epic 官方給它寫了專門的插件Visual Studio Tools for Unreal Engine來(lái)對(duì)接這套工具鏈。VS Code 沒(méi)有官方插件所以我們需要手動(dòng)把 UBT 的編譯任務(wù)、調(diào)試器的啟動(dòng)參數(shù)、IntelliSense 的包含路徑這三件事配好。理解了這一點(diǎn)后面所有配置就都順理成章了。2. 環(huán)境準(zhǔn)備與工具鏈?zhǔn)崂?.1 前置依賴清單在動(dòng)手配 VS Code 之前有幾樣?xùn)|西必須先裝好否則后面會(huì)各種報(bào)錯(cuò)。我把它們列成表格方便你對(duì)照檢查組件版本要求作用備注Unreal Engine 55.1 及以上引擎本體建議 5.3構(gòu)建系統(tǒng)更穩(wěn)定Visual Studio 2022社區(qū)版即可提供 MSVC 編譯器和 Windows SDK必須裝使用 C 的游戲開(kāi)發(fā)工作負(fù)載VS Code最新穩(wěn)定版代碼編輯器建議 1.85.NET SDK6.0 或 8.0UBT 運(yùn)行依賴UE5.3 之后用 .NET 6Windows SDK10.0.18362 以上編譯 Windows 平臺(tái)目標(biāo)裝 VS 時(shí)勾選這里有個(gè)很多人忽略的點(diǎn)即使你完全不用 Visual Studio 寫代碼也必須裝它。原因是 UE5 的 UBT 在 Windows 平臺(tái)下默認(rèn)調(diào)用 MSVC 的編譯器cl.exe和鏈接器而這些工具鏈?zhǔn)请S Visual Studio 一起安裝的。你可以不打開(kāi) VS但不能不裝它。我見(jiàn)過(guò)有人為了純凈環(huán)境只裝 Build Tools結(jié)果 UBT 找不到工具鏈報(bào)Unable to find a valid Visual Studio installation折騰半天。提示安裝 Visual Studio 時(shí)工作負(fù)載只勾使用 C 的游戲開(kāi)發(fā)就夠了單個(gè)組件里確保勾上Windows 10/11 SDK和MSVC v143 生成工具。不需要勾 .NET 桌面開(kāi)發(fā)那些省幾個(gè) G 空間。2.2 VS Code 必裝擴(kuò)展擴(kuò)展不在多在于精準(zhǔn)。UE5 C 開(kāi)發(fā)我實(shí)際用下來(lái)這幾個(gè)是剛需C/CMicrosoft 官方提供 IntelliSense、調(diào)試器cppvsdbg、代碼導(dǎo)航。這是核心沒(méi)有它 VS Code 就是個(gè)記事本。C/C Extension Pack包含 CMake Tools 等雖然 UE 不用 CMake但里面的一些輔助工具挺方便。Unreal Engine 4/5 Snippets提供 UPROPERTY、UFUNCTION 等宏的代碼片段寫反射標(biāo)記時(shí)省事。EditorConfig for VS Code統(tǒng)一代碼風(fēng)格UE 官方有 .editorconfig 文件裝上能自動(dòng)對(duì)齊縮進(jìn)。GitLensUE 項(xiàng)目文件多看 git blame 和提交歷史很有用。至于網(wǎng)上熱傳的什么 AI 代碼補(bǔ)全插件我個(gè)人建議在 UE 項(xiàng)目里謹(jǐn)慎使用。UE 的宏和模板代碼比如GENERATED_BODY()、TSubclassOf比較特殊很多補(bǔ)全工具會(huì)給出錯(cuò)誤建議反而干擾。等你把基礎(chǔ)環(huán)境跑通了再考慮加。2.3 生成項(xiàng)目文件一切的起點(diǎn)UE5 項(xiàng)目在 VS Code 里能正常工作的前提是項(xiàng)目目錄下存在.vscode文件夾和正確的編譯數(shù)據(jù)庫(kù)。而這兩樣?xùn)|西都需要通過(guò) UBT 生成。操作路徑是這樣的在 Epic Games Launcher 里找到你的引擎版本點(diǎn)引擎右側(cè)的下拉菜單選擇選項(xiàng)確認(rèn)勾選了引擎源碼如果你要調(diào)試引擎代碼的話。然后對(duì)你的.uproject文件右鍵選擇Generate Visual Studio project files。這一步會(huì)調(diào)用 UBT 生成.sln和.vcxproj文件。很多人會(huì)問(wèn)我不用 VS為什么還要生成 VS 項(xiàng)目文件因?yàn)?UBT 生成的這些文件里包含了完整的編譯配置信息VS Code 的 C/C 擴(kuò)展可以通過(guò)讀取這些信息來(lái)構(gòu)建 IntelliSense 數(shù)據(jù)庫(kù)。換句話說(shuō).vcxproj是 UBT 和 VS Code 之間的橋梁。生成完成后你會(huì)在項(xiàng)目根目錄看到Y(jié)ourProject.sln、Intermediate/ProjectFiles/等目錄。接下來(lái)打開(kāi) VS Code用打開(kāi)文件夾的方式打開(kāi)項(xiàng)目根目錄注意是根目錄不是 .sln 文件。3. 核心配置讓 IntelliSense 不再報(bào)紅3.1 c_cpp_properties.json 的正確寫法IntelliSense 報(bào)紅是新手最崩潰的問(wèn)題。滿屏紅波浪線但項(xiàng)目明明能編譯通過(guò)。根本原因是 VS Code 的 C/C 擴(kuò)展不知道 UE 的頭文件在哪、不知道那些宏是什么意思。解決辦法是在.vscode/c_cpp_properties.json里配置包含路徑和宏定義。但 UE 項(xiàng)目的包含路徑動(dòng)輒上百條手寫不現(xiàn)實(shí)。這里有個(gè)技巧直接從 UBT 生成的 .vcxproj 文件里提取。我實(shí)際用的配置長(zhǎng)這樣{ configurations: [ { name: Win64, includePath: [ ${workspaceFolder}/Source/**, ${workspaceFolder}/Intermediate/**, C:/Program Files/Epic Games/UE_5.3/Engine/Source/**, C:/Program Files/Epic Games/UE_5.3/Engine/Intermediate/** ], defines: [ UNICODE, _UNICODE, __UNREAL__, PLATFORM_WINDOWS1, WITH_EDITOR1, UE_BUILD_DEVELOPMENT1 ], compilerPath: C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.38.33130/bin/Hostx64/x64/cl.exe, cStandard: c17, cppStandard: c20, intelliSenseMode: windows-msvc-x64, compileCommands: ${workspaceFolder}/.vscode/compile_commands.json } ], version: 4 }關(guān)鍵點(diǎn)在于compileCommands這一項(xiàng)。如果你能生成compile_commands.jsonC/C 擴(kuò)展會(huì)優(yōu)先用它比手動(dòng)配 includePath 精準(zhǔn)得多。生成方法后面講。defines里的宏也很重要。__UNREAL__讓一些條件編譯代碼走對(duì)分支WITH_EDITOR1決定編輯器相關(guān)代碼是否參與 IntelliSense 分析。少了這些很多引擎頭文件會(huì)解析失敗。3.2 用 compile_commands.json 提升精度compile_commands.json是 Clang 工具鏈的標(biāo)準(zhǔn)編譯數(shù)據(jù)庫(kù)格式記錄了每個(gè)源文件的完整編譯命令。UE5 從 5.0 開(kāi)始支持通過(guò) UBT 生成這個(gè)文件。命令是這樣的在項(xiàng)目根目錄執(zhí)行C:\Program Files\Epic Games\UE_5.3\Engine\Build\BatchFiles\Build.bat YourProjectEditor Win64 Development -ProjectC:\Path\To\YourProject.uproject -WaitMutex -FromMsBuild -compdb -compdbformatjson執(zhí)行完后compile_commands.json會(huì)生成在Intermediate/目錄下。把它復(fù)制到.vscode/目錄然后在c_cpp_properties.json里指向它。注意這個(gè)命令每次改動(dòng)了模塊依賴比如在 .Build.cs 里加了新模塊后都要重新跑一遍否則 IntelliSense 會(huì)漏掉新模塊的頭文件路徑。我一般把它寫成一個(gè) .bat 腳本改完 Build.cs 就雙擊跑一下。3.3 處理 UE 宏導(dǎo)致的誤報(bào)即使配好了包含路徑UE 的一些宏還是會(huì)讓 IntelliSense 犯迷糊。最典型的是UPROPERTY()、UFUNCTION()、GENERATED_BODY()這些反射宏。C/C 擴(kuò)展不認(rèn)識(shí)它們會(huì)把它們當(dāng)成未定義的標(biāo)識(shí)符。解決辦法是在defines里加一個(gè)__INTELLISENSE__宏然后在代碼里用條件編譯繞過(guò)。不過(guò)更省事的做法是接受這些誤報(bào)。因?yàn)?UHTUnrealHeaderTool會(huì)在編譯前處理這些宏實(shí)際編譯是沒(méi)問(wèn)題的。你只需要在 VS Code 設(shè)置里把錯(cuò)誤波浪線的顯示級(jí)別調(diào)低或者用// NOLINT注釋臨時(shí)壓制。我個(gè)人的經(jīng)驗(yàn)是配好compile_commands.json之后90% 的誤報(bào)都會(huì)消失剩下的基本就是反射宏相關(guān)的習(xí)慣就好。4. 編譯任務(wù)把 UBT 接進(jìn) VS Code4.1 tasks.json 配置編譯任務(wù)VS Code 的編譯任務(wù)通過(guò).vscode/tasks.json定義。UE 項(xiàng)目的編譯本質(zhì)就是調(diào)用 UBT所以任務(wù)配置就是把 UBT 的命令行封裝一下。我的配置如下{ version: 2.0.0, tasks: [ { label: Build Editor (Development), type: shell, command: C:/Program Files/Epic Games/UE_5.3/Engine/Build/BatchFiles/Build.bat, args: [ YourProjectEditor, Win64, Development, -Project${workspaceFolder}/YourProject.uproject, -WaitMutex, -FromMsBuild ], group: { kind: build, isDefault: true }, problemMatcher: $msCompile, presentation: { echo: true, reveal: always, panel: shared } }, { label: Rebuild Editor, type: shell, command: C:/Program Files/Epic Games/UE_5.3/Engine/Build/BatchFiles/Build.bat, args: [ YourProjectEditor, Win64, Development, -Project${workspaceFolder}/YourProject.uproject, -WaitMutex, -FromMsBuild, -Clean ], problemMatcher: $msCompile } ] }幾個(gè)參數(shù)解釋一下YourProjectEditor是目標(biāo)名對(duì)應(yīng)你項(xiàng)目里Source/YourProject.Target.cs中定義的目標(biāo)。Win64是平臺(tái)Development是配置。-WaitMutex防止多個(gè) UBT 實(shí)例同時(shí)跑導(dǎo)致文件鎖沖突。-FromMsBuild讓輸出格式更規(guī)整方便 problemMatcher 解析錯(cuò)誤。problemMatcher設(shè)為$msCompile后編譯錯(cuò)誤會(huì)直接顯示在 VS Code 的問(wèn)題面板里點(diǎn)擊能跳轉(zhuǎn)到對(duì)應(yīng)代碼行。這個(gè)體驗(yàn)比在終端里翻日志強(qiáng)太多。4.2 快捷鍵綁定與一鍵編譯配好任務(wù)后按CtrlShiftB就能觸發(fā)默認(rèn)編譯任務(wù)。但 UE 項(xiàng)目經(jīng)常需要在編譯編輯器和編譯游戲之間切換我建議再綁幾個(gè)快捷鍵。在.vscode/keybindings.json里加[ { key: ctrlshifte, command: workbench.action.tasks.runTask, args: Build Editor (Development) }, { key: ctrlshiftr, command: workbench.action.tasks.runTask, args: Rebuild Editor } ]這樣CtrlShiftE編譯CtrlShiftR全量重建比去菜單里點(diǎn)快得多。4.3 Live Coding 與熱重載的配合UE5 的 Live Coding 是個(gè)好東西改完 C 代碼按CtrlAltF11就能熱重載不用重啟編輯器。但它和 VS Code 的編譯任務(wù)是兩套機(jī)制Live Coding 走的是引擎內(nèi)部的編譯流程VS Code 的 task 走的是 UBT 命令行。我的建議是日常小改動(dòng)用 Live Coding大改動(dòng)改頭文件、加新類、改模塊依賴用 VS Code 的 task 全量編譯。因?yàn)?Live Coding 對(duì)頭文件改動(dòng)的支持有限改了.h文件經(jīng)常需要重啟編輯器才能生效。實(shí)操心得Live Coding 編譯時(shí)VS Code 的 IntelliSense 數(shù)據(jù)庫(kù)不會(huì)自動(dòng)更新。如果你加了新函數(shù)代碼里會(huì)報(bào)未定義但實(shí)際能編譯通過(guò)。這時(shí)候手動(dòng)跑一次compile_commands.json生成命令或者重啟一下 C/C 擴(kuò)展命令面板搜 C/C: Reset IntelliSense Database就好了。5. 調(diào)試配置斷點(diǎn)、附加、變量查看5.1 launch.json 接入調(diào)試器VS Code 調(diào)試 UE 項(xiàng)目用的是 Microsoft 的 C/C 擴(kuò)展自帶的cppvsdbg調(diào)試器。配置寫在.vscode/launch.json{ version: 0.2.0, configurations: [ { name: Launch UE5 Editor (Debug), type: cppvsdbg, request: launch, program: C:/Program Files/Epic Games/UE_5.3/Engine/Binaries/Win64/UnrealEditor.exe, args: [ ${workspaceFolder}/YourProject.uproject, -game, -log ], stopAtEntry: false, cwd: ${workspaceFolder}, environment: [], console: externalTerminal, visualizerFile: C:/Program Files/Epic Games/UE_5.3/Engine/Extras/VisualStudioDebugging/Unreal.natvis }, { name: Attach to UE5 Editor, type: cppvsdbg, request: attach, processId: ${command:pickProcess} } ] }visualizerFile這一項(xiàng)是精髓。UE 引擎自帶一個(gè)Unreal.natvis文件它告訴調(diào)試器怎么漂亮地顯示 UE 的容器類型比如TArray、TMap、FString。沒(méi)有它你在調(diào)試窗口里看到的FString就是一坨內(nèi)存地址根本沒(méi)法看。args里的-game表示以游戲模式啟動(dòng)不帶編輯器 UI調(diào)試游戲邏輯時(shí)用這個(gè)。如果要調(diào)試編輯器本身去掉-game就行。5.2 附加到運(yùn)行中的編輯器更常用的場(chǎng)景是編輯器已經(jīng)開(kāi)著我想調(diào)試某個(gè)函數(shù)。這時(shí)候用 Attach to UE5 Editor 配置按 F5 后會(huì)彈出進(jìn)程列表選UnrealEditor.exe就行。附加調(diào)試有個(gè)坑必須確保你編譯的是 Debug 或 Development 配置且?guī)д{(diào)試符號(hào)。如果你編譯的是 Shipping 配置符號(hào)被剝離了斷點(diǎn)根本打不上。UE 默認(rèn)的 Development 配置是帶符號(hào)的放心用。5.3 斷點(diǎn)不生效的排查思路斷點(diǎn)打上去是空心圓灰色說(shuō)明調(diào)試器沒(méi)找到對(duì)應(yīng)的符號(hào)文件。排查順序確認(rèn)編譯配置是 Development 或 Debug不是 Shipping。確認(rèn)UnrealEditor.exe和你的模塊.pdb文件在同一目錄或符號(hào)路徑能找到。確認(rèn)附加的進(jìn)程是對(duì)的有時(shí)候開(kāi)了多個(gè)編輯器實(shí)例。檢查代碼是否真的被編譯進(jìn)去了——有時(shí)候改了代碼沒(méi)重新編譯斷點(diǎn)自然打不上。我遇到最多的情況是第 4 種。UE 項(xiàng)目模塊多有時(shí)候只編譯了部分模塊你以為改了其實(shí)跑的還是舊代碼。養(yǎng)成改完代碼先編譯再調(diào)試的習(xí)慣。6. 常見(jiàn)問(wèn)題與排查速查表6.1 IntelliSense 相關(guān)現(xiàn)象原因解決滿屏紅波浪線包含路徑缺失生成 compile_commands.json 并配置宏報(bào)未定義反射宏不被識(shí)別加__INTELLISENSE__宏或忽略跳轉(zhuǎn)定義失效數(shù)據(jù)庫(kù)未建立重置 IntelliSense 數(shù)據(jù)庫(kù)補(bǔ)全卡頓項(xiàng)目太大限制 includePath 范圍排除 Intermediate6.2 編譯相關(guān)現(xiàn)象原因解決UBT 找不到 VS工具鏈未安裝裝 VS 2022 游戲開(kāi)發(fā)工作負(fù)載編譯報(bào) mutex 錯(cuò)誤多實(shí)例沖突加-WaitMutex參數(shù)改了 .h 不生效Live Coding 限制全量編譯并重啟編輯器鏈接錯(cuò)誤 LNK2019模塊依賴缺失檢查 .Build.cs 的依賴列表6.3 調(diào)試相關(guān)現(xiàn)象原因解決斷點(diǎn)是空心圓符號(hào)未加載確認(rèn)編譯配置帶符號(hào)變量顯示亂碼natvis 未加載配置 visualizerFile附加進(jìn)程失敗權(quán)限不足以管理員身份運(yùn)行 VS Code調(diào)試卡死斷點(diǎn)太多減少斷點(diǎn)用條件斷點(diǎn)6.4 獨(dú)家避坑技巧說(shuō)幾個(gè)文檔里不會(huì)寫、但我實(shí)際踩過(guò)的坑第一路徑里的空格和中文。UE 的 UBT 對(duì)路徑中的空格處理還算 OK但對(duì)中文路徑支持很差。如果你的項(xiàng)目路徑里有中文編譯大概率會(huì)失敗。我建議所有 UE 項(xiàng)目都放在純英文、無(wú)空格的路徑下比如D:\UEProjects\MyGame。第二殺毒軟件拖慢編譯。Windows Defender 實(shí)時(shí)掃描會(huì)嚴(yán)重拖慢 UBT 的編譯速度尤其是大項(xiàng)目。把項(xiàng)目目錄和引擎目錄加入排除列表編譯速度能快 30% 以上。第三VS Code 的工作區(qū)設(shè)置。如果你同時(shí)開(kāi)多個(gè) UE 項(xiàng)目建議用多根工作區(qū)Multi-root Workspace每個(gè)項(xiàng)目一個(gè)文件夾避免 IntelliSense 數(shù)據(jù)庫(kù)互相干擾。第四定期清理 Intermediate。UE 的 Intermediate 目錄會(huì)越積越大有時(shí)候還會(huì)因?yàn)榫彺鎸?dǎo)致奇怪的編譯錯(cuò)誤。遇到莫名其妙的編譯失敗先刪掉Intermediate/和Saved/目錄重新生成能解決一半問(wèn)題。7. 我個(gè)人的實(shí)際使用體會(huì)這套配置我從 UE5.1 一直用到 5.4中間經(jīng)歷過(guò)幾次引擎升級(jí)導(dǎo)致的配置失效但整體框架沒(méi)變過(guò)。VS Code 寫 UE 的體驗(yàn)說(shuō)實(shí)話在純 C 代碼編輯和導(dǎo)航上比 Visual Studio 輕快不少尤其是機(jī)器配置一般的時(shí)候開(kāi) VS 那個(gè)加載速度真的勸退。但它也有明顯的短板藍(lán)圖和 C 的混合調(diào)試不如 VS 順暢UE 的一些編輯器專用工具比如藍(lán)圖調(diào)試器、性能分析器在 VS Code 里沒(méi)有對(duì)應(yīng)集成。所以我的實(shí)際工作流是日常寫 C 用 VS Code需要深度調(diào)試藍(lán)圖或做性能分析時(shí)切回 Visual Studio。兩個(gè) IDE 共用同一套 UBT 工具鏈項(xiàng)目文件是通用的切換成本很低。最后分享一個(gè)小技巧把常用的 UBT 命令編譯、生成項(xiàng)目文件、清理都寫成.bat腳本放在項(xiàng)目根目錄然后在 VS Code 的 tasks.json 里引用這些腳本。這樣即使換了引擎版本只需要改腳本里的引擎路徑tasks.json 不用動(dòng)。這個(gè)習(xí)慣幫我省了不少升級(jí)時(shí)的重復(fù)勞動(dòng)。