剛幫團(tuán)隊(duì)里一位同事排查了一個(gè)讓人血壓升高的場(chǎng)景Visual Studio 2022 打開(kāi)后想新建一個(gè)控制臺(tái)項(xiàng)目結(jié)果“創(chuàng)建新項(xiàng)目”對(duì)話框里干干凈凈一條模板都搜不到。不信邪關(guān)掉重開(kāi)繼續(xù)空白。再一看連“新建文件”那邊也只剩下幾個(gè)孤零零的項(xiàng)之前好好的 .cs、.cpp 模板全不見(jiàn)了。這種Visual Studio 新建項(xiàng)目和文件問(wèn)題在社區(qū)里搜一下能出來(lái)一大把原因五花八門(mén)但套路是固定的要么模板緩存損壞要么擴(kuò)展在搗亂要么根本就是 SDK 和路徑的問(wèn)題。這篇文章就是我這次完整排查過(guò)程的記錄我把每一步怎么查、怎么修復(fù)、為什么要這么做都寫(xiě)清楚了適合被這個(gè)問(wèn)題卡住的新手也適合想徹底搞明白原理的老手。1. 新建項(xiàng)目時(shí)模板列表空白先分清是緩存壞了還是擴(kuò)展崩了1.1 模板加載機(jī)制決定了它必然會(huì)出這種問(wèn)題先說(shuō)一個(gè)容易被忽略的事實(shí)Visual Studio 新裝好之后默認(rèn)的模板文件并不是現(xiàn)成的“可用狀態(tài)”它需要在 IDE 啟動(dòng)時(shí)經(jīng)過(guò)一輪索引、注冊(cè)和本地緩存寫(xiě)入之后才會(huì)出現(xiàn)在新建項(xiàng)目對(duì)話框里。具體點(diǎn)說(shuō)模板源文件散落在兩個(gè)地方。項(xiàng)目模板Project Templates放在安裝目錄的Templates\ProjectTemplates下條目模板Item Templates里的那些單文件模板放在Templates\ItemTemplates下。為了加快每次啟動(dòng)的速度VS 會(huì)把這兩類(lèi)模板的元數(shù)據(jù)、圖標(biāo)、描述集中生成一份“緩存”緩存放你的用戶(hù)目錄里。路徑一般是%LocalAppData%\Microsoft\VisualStudio\版本號(hào)_實(shí)例ID\ProjectTemplatesCache %LocalAppData%\Microsoft\VisualStudio\版本號(hào)_實(shí)例ID\ItemTemplatesCache這套設(shè)計(jì)本身沒(méi)問(wèn)題問(wèn)題在于“緩存”這玩意兒最怕兩件事一是生成緩存時(shí)被打斷比如更新安裝到一半強(qiáng)制關(guān)機(jī)二是緩存文件被某些程序當(dāng)作垃圾清理掉。一旦本地緩存和實(shí)際模板源對(duì)不上VS 啟動(dòng)時(shí)掃到的就是個(gè)殘缺的索引表現(xiàn)出來(lái)就是——新建項(xiàng)目對(duì)話框里一個(gè)模板都看不到或者只能看到幾個(gè)系統(tǒng)自帶的“空白解決方案”之類(lèi)的項(xiàng)。1.2 接口完整還是空白兩條修復(fù)路徑先試哪條遇到模板列表空白我的建議是按下面順序判斷不要上來(lái)就重裝。第一步打開(kāi) Visual Studio Installer看你當(dāng)前安裝的版本、工作負(fù)載是否完整。有時(shí)候并不是模板壞了而是某次更新之后工作負(fù)載被部分移除對(duì)應(yīng)語(yǔ)言的模板自然就沒(méi)了。確認(rèn)工作負(fù)載沒(méi)問(wèn)題之后再做第二步刪除模板緩存重啟。這一步能解決一大半“索引損壞”類(lèi)問(wèn)題。因?yàn)?VS 在啟動(dòng)時(shí)如果發(fā)現(xiàn)ProjectTemplatesCache目錄不存在會(huì)重新掃描模板源生成新的緩存。具體操作# 先關(guān)掉所有 VS 實(shí)例 # 找到你的 版本號(hào)_實(shí)例ID 目錄 Get-ChildItem $env:LOCALAPPDATA\Microsoft\VisualStudio -Directory | Select-Object Name # 刪除模板緩存 Remove-Item -Recurse -Force $env:LOCALAPPDATA\Microsoft\VisualStudio\你的版本目錄\ProjectTemplatesCache Remove-Item -Recurse -Force $env:LOCALAPPDATA\Microsoft\VisualStudio\你的版本目錄\ItemTemplatesCache刪完重新打開(kāi) VS選任意項(xiàng)目類(lèi)型VS 后臺(tái)會(huì)自動(dòng)重建緩存。如果等了一會(huì)兒還是空再往下看第三條。第三步才是排查擴(kuò)展。很多第三方擴(kuò)展會(huì)自帶模板比如一些社區(qū) UI 庫(kù)、代碼生成工具它們安裝時(shí)會(huì)往模板目錄寫(xiě)入自己的模板文件。有個(gè)很典型的坑某個(gè)擴(kuò)展被更新到不兼容的版本之后它的模板索引寫(xiě)入失敗但 VS 在掃描索引時(shí)又把“失敗的這部分”也算進(jìn)去了結(jié)果整個(gè)模板列表反而啟動(dòng)失敗。之前碰到過(guò)某圖像處理庫(kù)的擴(kuò)展把模板列表拖垮的情況。排查方式很硬核但效率很高按住Shift鍵啟動(dòng) Visual Studio進(jìn)入“安全模式”。安全模式下所有第三方擴(kuò)展都會(huì)被禁用。如果安全模式下模板正常那罪魁就是擴(kuò)展逐個(gè)禁用再啟動(dòng)就能定位。1.3 殺軟和安全策略也參與過(guò)“失蹤案”還有一個(gè)經(jīng)常被忽略的元兇安全軟件。模板源目錄在 VS 安裝目錄下本身就容易被實(shí)時(shí)掃描攔截。我遇到過(guò)不止一次某安全軟件誤把Templates目錄下的一些模板文件當(dāng)成了“低活躍度文件”隔離掉導(dǎo)致 VS 掃描時(shí)文件缺失。確認(rèn)方法也很簡(jiǎn)單打開(kāi) Visual Studio Installer —— “修復(fù)”修復(fù)完成之后再測(cè)。如果修復(fù)完短暫恢復(fù)正常過(guò)一段時(shí)間又復(fù)發(fā)那你八成就是安全軟件在后臺(tái)持續(xù)動(dòng)手腳。處理方式是把 VS 安裝目錄、用戶(hù)目錄下的VisualStudio文件夾加入安全軟件的排除列表。2. 項(xiàng)目創(chuàng)建成功卻打不開(kāi)多半不是VS的錯(cuò)是SDK和路徑在搗亂2.1 目標(biāo)框架缺失時(shí)VS的表現(xiàn)有多迷惑模板列表恢復(fù)之后更常見(jiàn)的是另一類(lèi)問(wèn)題新建項(xiàng)目時(shí)一切正常向?qū)б沧咄炅私Y(jié)果項(xiàng)目一創(chuàng)建出來(lái)就打不開(kāi)錯(cuò)誤列表里報(bào)的還不是“找不到 SDK”這種直白的話而是一堆MSB3644、NETSDK1045這類(lèi)讓人摸不著頭腦的編號(hào)。其實(shí)這就是目標(biāo)框架與實(shí)際安裝的 .NET SDK 版本對(duì)不上。舉個(gè)例子你新建項(xiàng)目時(shí)選了.NET 8.0但機(jī)器上實(shí)際只裝了.NET 6.0的 SDKVS 向?qū)П旧聿粫?huì)攔著你它只管把項(xiàng)目文件生成出來(lái)。等到還原階段構(gòu)建系統(tǒng)才發(fā)現(xiàn)找不到對(duì)應(yīng)版本于是拋錯(cuò)。而且這個(gè)錯(cuò)經(jīng)常出現(xiàn)在“某個(gè)子文件加載失敗”的偽裝下。這時(shí)候不要急著折騰 VS先在命令行敲一句dotnet --list-sdks dotnet --list-runtimes看看本機(jī)到底有哪些版本。然后右鍵項(xiàng)目 —— “屬性” —— “目標(biāo)框架”改成實(shí)際存在的那一檔問(wèn)題立刻解決。這個(gè)單子適用于 .NET Core 后的所有項(xiàng)目。2.2 中文路徑、符號(hào)字符和 OneDrive 的連鎖反應(yīng)另一個(gè)經(jīng)典場(chǎng)景是項(xiàng)目路徑里的“坑”。Visual Studio 對(duì)路徑里的非 ASCII 字符和部分特殊符號(hào)一直都很敏感。中文用戶(hù)名、帶空格的文件夾、帶#或的目錄都有可能在項(xiàng)目生成階段引發(fā)怪異問(wèn)題。不是 100% 一定出錯(cuò)但一旦出錯(cuò)報(bào)錯(cuò)信息往往指向完全不相干的地方比如“找不到文件 license.rtf”或者“無(wú)法解析主引用”。更隱蔽的是把項(xiàng)目建在 OneDrive 同步目錄下。VS 在構(gòu)建時(shí)會(huì)創(chuàng)建大量臨時(shí)文件同步工具對(duì)文件流的占用會(huì)導(dǎo)致 VS 這邊文件被占用、寫(xiě)入失敗輕則智能提示延遲重則項(xiàng)目加載直接卡死。我自己的習(xí)慣是建項(xiàng)目一律放在本地磁盤(pán)的非系統(tǒng)盤(pán)根目錄比如D:\Projects從來(lái)不用文檔目錄更不用同步盤(pán)。新建項(xiàng)目時(shí)位置一欄默認(rèn)指向C:\Users\用戶(hù)名\source\repos建議你改成根路徑下的固定目錄。這不是潔癖是從根源上避開(kāi)后面一堆怪問(wèn)題。2.3 項(xiàng)目文件損壞時(shí)的搶救次序還有一種情況項(xiàng)目文件本身壞了。.csproj或.vcxproj是 XML 文件如果之前編輯時(shí)意外沖突、或突發(fā)斷電導(dǎo)致寫(xiě)入不完整打開(kāi)項(xiàng)目時(shí) VS 會(huì)提示“項(xiàng)目文件已損壞”或干脆靜默加載失敗。搶救次序建議這樣先備份壞文件。用文本編輯器打開(kāi)檢查 XML 結(jié)構(gòu)是否完整看是否缺少閉合標(biāo)簽。如果內(nèi)容很正常但 VS 就是不認(rèn)刪掉.vs隱藏目錄它保存了解決方案的用戶(hù)級(jí)緩存重新打開(kāi)。再不行對(duì)比同類(lèi)型項(xiàng)目模板生成的新.csproj把殘留節(jié)點(diǎn)移植過(guò)去。這個(gè)方法我救過(guò)好幾個(gè)項(xiàng)目最核心的原則是——先別重裝 VS先看項(xiàng)目文件本身。3. 新建文件是空的、模板丟失、高亮失效單文件模板的完整排查鏈路3.1 單文件模板和項(xiàng)目模板是兩套系統(tǒng)很多人的排查止步在“項(xiàng)目能建了”但“新建文件”還有問(wèn)題。我要提醒一句單文件模板Item Template和項(xiàng)目模板Project Template在 VS 里是兩套獨(dú)立的注冊(cè)路徑項(xiàng)目模板正常不代表單文件模板正常。新建文件出問(wèn)題的典型表現(xiàn)是右鍵項(xiàng)目 —— “添加” —— “新建項(xiàng)”對(duì)話框里列表稀稀拉拉甚至沒(méi)有任何模板另一種情況是模板在點(diǎn)確定后生成的是一個(gè)空文件或者一個(gè)擴(kuò)展名錯(cuò)誤的文件。這背后的邏輯是這樣的添加新項(xiàng)對(duì)話框讀取的緩存和新建項(xiàng)目對(duì)話框讀的緩存是兩個(gè)目錄。所以按第一章的路子刪除緩存時(shí)要兩步都做別只刪了ProjectTemplatesCache就收工。我遇到過(guò)一個(gè)場(chǎng)景項(xiàng)目模板全好了新建項(xiàng)里.xaml、.cs全都憑空消失排查半天就因?yàn)樵谝淮握`清理中只刪了一半緩存。3.2 手工驗(yàn)證本地緩存是否還在如果刪緩存沒(méi)有用下一步要直接看模板源有沒(méi)有問(wèn)題。Visual Studio 安裝目錄下的模板源路徑是安裝路徑\Common7\IDE\ProjectTemplates 安裝路徑\Common7\IDE\ItemTemplates不同語(yǔ)言、不同工作負(fù)載的模板按子目錄區(qū)分。打開(kāi)對(duì)應(yīng)目錄看看里面的模板文件夾是否完整。如果目錄里的文件還在那問(wèn)題依然出在本地緩存身上。如果目錄本身就是半空的那多半是安裝器問(wèn)題直接走修復(fù)安裝。還有一個(gè)比較隱蔽的這些模板文件內(nèi)部有.vstemplateXML 文件它聲明了模板的名稱(chēng)、圖標(biāo)、向?qū)ь?lèi)型。如果某個(gè)擴(kuò)展在安裝時(shí)改寫(xiě)了這個(gè)文件但又沒(méi)寫(xiě)完整VS 在解析它時(shí)會(huì)跳過(guò)整個(gè)模板組。表現(xiàn)就是部分模板缺失不是全部空白。對(duì)這種“部分缺失”不要重建緩存也不用重裝直接把損壞的.vstemplate和對(duì)應(yīng)文件夾刪掉讓緩存重建時(shí)跳過(guò)它就行。3.3 高亮和智能提示消失背后的 MEF 組件緩存最后一種“新建文件”問(wèn)題可能?chē)樀讲簧偃宋募芙ㄕZ(yǔ)法高亮沒(méi)了智能提示也沒(méi)了整個(gè)文件被當(dāng)成純文本處理。這是語(yǔ)言服務(wù)沒(méi)有正常加載通常和 MEFManaged Extensibility Framework組件緩存損壞有關(guān)。VS 會(huì)把擴(kuò)展組件的元數(shù)據(jù)編入ComponentModelCache目錄這個(gè)緩存損壞時(shí)IDE 里各種依賴(lài)擴(kuò)展能力的功能都會(huì)失效最典型的就是語(yǔ)言服務(wù)。處理辦法比想象中簡(jiǎn)單Remove-Item -Recurse -Force $env:LOCALAPPDATA\Microsoft\VisualStudio\版本目錄\ComponentModelCache刪除后重啟 VS它會(huì)重新掃描組件。注意第一次重啟會(huì)比較慢這是正常的等它把索引建立完就好。4. 排查三大件的實(shí)操手冊(cè)ActivityLog、緩存重建、修復(fù)安裝4.1 用 devenv /log 捕獲精確報(bào)錯(cuò)上面聊了那么多可能的成因?qū)崙?zhàn)中第一步永遠(yuǎn)不是猜而是看日志。VS 自己帶了一個(gè)日志開(kāi)關(guān)只是沒(méi)在 GUI 里給普通用戶(hù)暴露。關(guān)閉所有 VS 實(shí)例打開(kāi)“開(kāi)發(fā)者命令提示符”或 PowerShell執(zhí)行devenv /log用這種方式啟動(dòng) VS 之后操作一遍“新建項(xiàng)目”或“新建文件”讓問(wèn)題復(fù)現(xiàn)然后退出 VS去這個(gè)位置找到日志%LocalAppData%\Microsoft\VisualStudio\版本目錄\ActivityLog.xml這個(gè) XML 文件記錄了整個(gè)會(huì)話的所有活動(dòng)包括擴(kuò)展加載、模板掃描、錯(cuò)誤異常。搜索關(guān)鍵詞Error、Exception、Template基本能把問(wèn)題鎖定到具體模塊上。學(xué)會(huì)看這份日志比什么重裝大法都靠譜。因?yàn)樗艽_認(rèn)一個(gè)關(guān)鍵問(wèn)題模板掃描到底有沒(méi)有發(fā)生如果掃描根本沒(méi)發(fā)生那是啟動(dòng)鏈路的問(wèn)題如果掃描發(fā)生了但模板數(shù)量為 0那是源文件的問(wèn)題。這一步能把排查時(shí)間縮短一大半。4.2 緩存重建立即見(jiàn)效的正確打開(kāi)方式緩存刪除這個(gè)操作在好幾處都提過(guò)但它講究一個(gè)順序順序不對(duì)會(huì)白做。正確流程關(guān)閉全部 VS 實(shí)例包括后臺(tái)的 VS 后臺(tái)進(jìn)程。刪ProjectTemplatesCache和ItemTemplatesCache。可選刪除ComponentModelCache。啟動(dòng) VS不要立刻打開(kāi)任何項(xiàng)目停在起始頁(yè)等模板索引重建。這里有個(gè)很容易踩的坑如果你在刪除緩存后直接雙擊打開(kāi)了一個(gè)解決方案VS 的模板索引可能被跳過(guò)或延遲構(gòu)建你看到的現(xiàn)象就是“還是空白”。正確姿勢(shì)是先開(kāi) VS、再新建項(xiàng)目讓“新建項(xiàng)目”這一步主動(dòng)觸發(fā)模板掃描。4.3 修復(fù)安裝什么時(shí)候用什么時(shí)候只能重裝如果日志顯示模板源目錄都不完整那大概率要從安裝器層面解決了。在 Visual Studio Installer 界面里對(duì)著當(dāng)前安裝的版本點(diǎn)“更多” —— “修復(fù)”。它會(huì)把缺失的文件重新補(bǔ)齊同時(shí)保留你的配置和擴(kuò)展。大多數(shù)模板源丟失的問(wèn)題在這一步都能被解決。需要強(qiáng)調(diào)修復(fù)安裝不等同于重裝不會(huì)把你的擴(kuò)展、賬戶(hù)配置、項(xiàng)目設(shè)置全部復(fù)位可以放心執(zhí)行。但如果連修復(fù)安裝都失敗或者修復(fù)后問(wèn)題依舊那才考慮卸載重裝。重裝前建議備份好這幾樣你的keybindings設(shè)置、主題配置、已安裝擴(kuò)展清單。擴(kuò)展清單可以用導(dǎo)出向?qū)蛇@樣重裝之后一把梭恢復(fù)環(huán)境。5. 防止新建項(xiàng)目又翻車(chē)的幾個(gè)習(xí)慣5.1 給擴(kuò)展做“體檢報(bào)告”排查過(guò)這么多次之后我對(duì) VS 擴(kuò)展的態(tài)度變得非常保守。擴(kuò)展是 Visual Studio 新建項(xiàng)目和文件問(wèn)題最常見(jiàn)的催化劑之一尤其是那些自帶模板的擴(kuò)展?，F(xiàn)在我的習(xí)慣是不裝擴(kuò)展超過(guò) 15 個(gè)每次更新 VS 大版本前先卸載所有可能帶模板的擴(kuò)展新裝擴(kuò)展后不立刻開(kāi)工先建個(gè)臨時(shí)項(xiàng)目測(cè)試模板是否正常。這不算過(guò)度謹(jǐn)慎。擴(kuò)展的加載機(jī)制決定了它會(huì)影響整個(gè) IDE 的啟動(dòng)鏈路一個(gè)不兼容的擴(kuò)展能拖垮的不只是它自己的功能還能連帶破壞模板索引。5.2 管理好項(xiàng)目目錄和用戶(hù)權(quán)限把默認(rèn)項(xiàng)目目錄改到非系統(tǒng)盤(pán)、非同步盤(pán)之后新建項(xiàng)目時(shí)的“權(quán)限不足”類(lèi)問(wèn)題會(huì)少一大截。另外還要留意用戶(hù)目錄的權(quán)限變動(dòng)。有些系統(tǒng)清理工具會(huì)在“優(yōu)化”時(shí)重置%LocalAppData%下某些目錄的 ACL 權(quán)限導(dǎo)致 VS 無(wú)法寫(xiě)入緩存。如果某一天突然出現(xiàn)“無(wú)法創(chuàng)建項(xiàng)目”“找不到路徑”這類(lèi)提示先去事件查看器看看有沒(méi)有Access Denied記錄有的話重設(shè)一下對(duì)應(yīng)文件夾的權(quán)限就行。5.3 安裝更新前后的存檔動(dòng)作Visual Studio 每次打補(bǔ)丁后都有一定概率碰到模板重建問(wèn)題這不是 bug是正常的索引變化。我的建議是更新之前用導(dǎo)出向?qū)О涯愕臄U(kuò)展列表導(dǎo)出存一份更新之后的第一件事不是打開(kāi)老項(xiàng)目而是先新建一個(gè)測(cè)試項(xiàng)目確認(rèn)模板鏈路暢通再回去干正事。這個(gè)習(xí)慣幫我省了不知道多少個(gè)“周一早上打開(kāi) VS 發(fā)現(xiàn)模板全套消失”的搶救時(shí)間。新建項(xiàng)目這個(gè)入口在 VS 里承載著幾乎所有后續(xù)開(kāi)發(fā)行為它一旦出問(wèn)題整個(gè)人的節(jié)奏全被打亂。模板緩存、SDK 版本、項(xiàng)目路徑、擴(kuò)展兼容性這套鏈路只要摸清了Visual Studio 新建項(xiàng)目和文件問(wèn)題就再也不是什么嚇人的玄學(xué)了。