你有沒(méi)有遇到過(guò)這種情況微信開(kāi)發(fā)者工具一切正常新建項(xiàng)目也能跑但一導(dǎo)入某個(gè)從網(wǎng)上下載或同事拷過(guò)來(lái)的項(xiàng)目彈窗里直接甩出一行紅色報(bào)警——[ app.json 文件內(nèi)容錯(cuò)誤] app.json: app.json 未找到 (env: Windows, mp, 1.05.2204250 lib: 3.7.7)。我第一次碰到這個(gè)報(bào)錯(cuò)時(shí)第一反應(yīng)是趕緊打開(kāi)項(xiàng)目文件夾看app.json還在不在結(jié)果文件好端端地躺在那里換了好幾個(gè)導(dǎo)入方式還是一樣報(bào)錯(cuò)那一瞬間真的懷疑人生。這篇文章就是專(zhuān)門(mén)圍繞這個(gè)報(bào)錯(cuò)展開(kāi)的。我會(huì)從app.json在微信小程序項(xiàng)目里的具體地位說(shuō)起分析工具在Windows環(huán)境下報(bào)未找到的幾類(lèi)根因再給出一套完整可直接照做的排查步驟。無(wú)論你是剛?cè)肟有〕绦虻男率诌€是被app.json未找到反復(fù)折騰的老開(kāi)發(fā)都能按圖索驥、少走彎路。1. 先搞懂這個(gè)報(bào)錯(cuò)到底在說(shuō)什么app.json的角色與報(bào)錯(cuò)本質(zhì)1.1 app.json在小程序項(xiàng)目里到底多重要app.json是微信小程序的全局配置文件可以把它理解成整個(gè)項(xiàng)目的總編排表。pages數(shù)組里注冊(cè)的每一個(gè)頁(yè)面決定小程序能跳轉(zhuǎn)到哪里數(shù)組第一項(xiàng)就是首頁(yè)window字段統(tǒng)一設(shè)置導(dǎo)航欄背景色、標(biāo)題文字、下拉刷新開(kāi)關(guān)tabBar配置底部導(dǎo)航欄subPackages聲明分包結(jié)構(gòu)networkTimeout控制請(qǐng)求超時(shí)時(shí)間還需要在這里聲明插件、權(quán)限、worker、獨(dú)立分包等等。開(kāi)發(fā)者工具在編譯啟動(dòng)時(shí)最先做的動(dòng)作之一就是定位并加載這個(gè)文件。一旦加載失敗整個(gè)項(xiàng)目就處于無(wú)法識(shí)別結(jié)構(gòu)的狀態(tài)工具不會(huì)繼續(xù)去編譯pages目錄下的wxml、wxss和js而是直接中斷流程在控制臺(tái)拋出行錯(cuò)誤信息。所以這個(gè)報(bào)錯(cuò)對(duì)項(xiàng)目來(lái)說(shuō)是致命級(jí)的不是忽略掉就能繼續(xù)開(kāi)發(fā)的那種warning。我遇到過(guò)不少初學(xué)者以為app.json是可以隨便刪的配置文件刪掉也不影響頁(yè)面編譯結(jié)果工具立刻報(bào)錯(cuò)。這里可以明確app.json不是可有可無(wú)的它和小程序的啟動(dòng)流程直接掛鉤缺失會(huì)導(dǎo)致程序無(wú)法啟動(dòng)。這就像一套房子的總電閘少一個(gè)房間的燈開(kāi)關(guān)不影響但總電閘被拉下來(lái)了整屋都得黑。1.2 未找到和文件內(nèi)容錯(cuò)誤之間隔著一層誤解報(bào)錯(cuò)信息中括號(hào)里的描述是文件內(nèi)容錯(cuò)誤冒號(hào)后面的具體文本卻是app.json未找到。這兩者對(duì)排查方向的指導(dǎo)意義完全不同。從報(bào)錯(cuò)機(jī)制看工具在讀取app.json時(shí)通常分兩步第一步是定位文件即按照工程配置找到app.json的物理路徑找不到就會(huì)報(bào)未找到第二步是解析內(nèi)容即把文件內(nèi)容按JSON格式解析語(yǔ)法出錯(cuò)會(huì)報(bào)具體的解析異常比如Unexpected token、Expecting STRING等。標(biāo)題中這次報(bào)錯(cuò)屬于第一階段就失敗了——工具壓根沒(méi)能在預(yù)期位置找到文件。但在實(shí)際使用時(shí)這兩類(lèi)錯(cuò)誤經(jīng)常被工具籠統(tǒng)地歸在同一個(gè)紅色彈窗里導(dǎo)致很多人一看到未找到就去反復(fù)改JSON內(nèi)容比如給字段加引號(hào)、去注釋結(jié)果錯(cuò)誤紋絲不動(dòng)。理解了這個(gè)機(jī)制上的區(qū)別你就能第一時(shí)間意識(shí)到問(wèn)題大概率出在文件路徑、文件命名、目錄結(jié)構(gòu)這些外圍因素上而不是JSON里某一行的語(yǔ)法問(wèn)題。這條認(rèn)知上的轉(zhuǎn)變能幫你省下一大半無(wú)用功。另外報(bào)錯(cuò)尾部那一串(env: Windows, mp, 1.05.2204250 lib: 3.7.7)也不是亂碼。env: Windows表示當(dāng)前運(yùn)行環(huán)境是Windows操作系統(tǒng)mp代表miniprogram說(shuō)明是標(biāo)準(zhǔn)小程序模式而非小游戲或大程序1.05.2204250是開(kāi)發(fā)者工具本身的構(gòu)建版本號(hào)lib: 3.7.7是項(xiàng)目使用的基礎(chǔ)庫(kù)版本。這些信息在排查工具版本兼容性問(wèn)題時(shí)非常有用后面第六節(jié)會(huì)展開(kāi)說(shuō)。2. 最可能的四大誘因排查項(xiàng)目結(jié)構(gòu)、文件命名、路徑配置與緩存2.1 項(xiàng)目根目錄選錯(cuò)是最常見(jiàn)的原因我在各種技術(shù)社區(qū)的求助帖里觀察到一個(gè)規(guī)律凡是報(bào)app.json未找到一半以上是導(dǎo)入項(xiàng)目時(shí)目錄選錯(cuò)了。微信開(kāi)發(fā)者工具的導(dǎo)入項(xiàng)目要求你選擇的是小程序工程的根目錄也就是直接包含app.js、app.json、app.wxss的那一層。但日常開(kāi)發(fā)中項(xiàng)目在Git倉(cāng)庫(kù)里往往有兩級(jí)甚至三級(jí)目錄結(jié)構(gòu)比如repo/ ├── miniprogram/ - 真正的小程序代碼在這里 │ ├── app.js │ ├── app.json │ └── pages/ ├── cloudfunctions/ └── README.md如果導(dǎo)入時(shí)選的是repo這一層工具只看到cloudfunctions和README.md自然找不到app.json。處理方式有兩種一是把導(dǎo)入路徑精確到miniprogram目錄二是保留外層導(dǎo)入但在project.config.json中添加miniprogramRoot: miniprogram/告訴工具子目錄的位置云開(kāi)發(fā)模板默認(rèn)就是這種結(jié)構(gòu)。這個(gè)決策點(diǎn)直接影響后續(xù)命令行工具的路徑、上傳代碼的目錄最好一開(kāi)始就確認(rèn)清楚。還有一類(lèi)場(chǎng)景同事發(fā)來(lái)一個(gè)壓縮包解壓后里面還套著一層文件夾。Windows解壓zip時(shí)會(huì)自動(dòng)把外層目錄也解出來(lái)同時(shí)包里可能包含了用戶(hù)自己創(chuàng)建的項(xiàng)目-最終版殼目錄。你在選擇項(xiàng)目路徑時(shí)多進(jìn)了一層報(bào)錯(cuò)就來(lái)了。判斷標(biāo)準(zhǔn)很簡(jiǎn)單打開(kāi)資源管理器看當(dāng)前路徑下有沒(méi)有app.json這個(gè)文件沒(méi)有就再進(jìn)一層或退一層。2.2 Windows資源管理器把文件名變成了app.json.txt這是Windows用戶(hù)特有、又極其隱蔽的一個(gè)坑。資源管理器默認(rèn)不顯示已知類(lèi)型文件的擴(kuò)展名你在新建→文本文檔后順手重命名為app.json系統(tǒng)實(shí)際創(chuàng)建的文件名是app.json.txt但界面上只顯示app.json。微信開(kāi)發(fā)者工具去讀文件時(shí)按精確文件名找app.json發(fā)現(xiàn)找不到于是報(bào)未找到。怎么確認(rèn)在資源管理器中依次點(diǎn)擊查看→勾選文件擴(kuò)展名或者選中該文件右鍵→屬性→看文件名字段的完整后綴。確認(rèn)是app.json.txt后把它重命名成真正的app.json中間會(huì)彈出一個(gè)如果改變文件擴(kuò)展名可能會(huì)導(dǎo)致文件不可用。確實(shí)要更改嗎的對(duì)話框毫不猶豫點(diǎn)是。我提醒很多學(xué)員檢查這個(gè)點(diǎn)的時(shí)候他們第一反應(yīng)都是不可能我明明看到叫app.json。結(jié)果勾選擴(kuò)展名顯示后一個(gè)個(gè)都沉默了。Windows這個(gè)默認(rèn)行為坑過(guò)的人真的非常多尤其是在Windows 11上新版資源管理器把查看→顯示→文件擴(kuò)展名的入口藏得很深需要依次展開(kāi)查看→顯示→文件擴(kuò)展名三級(jí)菜單。如果你用的是舊Windows版本可以打開(kāi)控制面板→文件夾選項(xiàng)→查看→取消勾選隱藏已知文件類(lèi)型的擴(kuò)展名。2.3 project.config.json中miniprogramRoot指向錯(cuò)誤如果說(shuō)目錄選錯(cuò)是新人錯(cuò)那miniprogramRoot指向錯(cuò)誤就是很多老手也會(huì)翻車(chē)的地方。官方提供的云開(kāi)發(fā)模板、或從uni-app、Taro這類(lèi)跨端框架拉下來(lái)的工程項(xiàng)目根目錄往往不是小程序代碼的宿主目錄。此時(shí)project.config.json里的miniprogramRoot字段負(fù)責(zé)告訴工具小程序的代碼在哪個(gè)子目錄里。舉個(gè)真實(shí)例子。我接手過(guò)一個(gè)項(xiàng)目目錄很規(guī)范project/ ├── project.config.json ├── src/ │ ├── app.js │ ├── app.json │ └── pages/ ├── dist/第一次導(dǎo)入時(shí)工具也報(bào)了app.json未找到。打開(kāi)project.config.json一看miniprogramRoot被寫(xiě)成了./dist/這是別人在構(gòu)建流程里配置的產(chǎn)物目錄里面只有打包出來(lái)的JS和WXML恰好沒(méi)有app.json。當(dāng)時(shí)是直接在dist目錄跑開(kāi)發(fā)預(yù)覽根本沒(méi)注意根配置。后來(lái)把miniprogramRoot改回./src/或者根據(jù)實(shí)際布局改成相對(duì)路徑就正常了。排查時(shí)有個(gè)高效動(dòng)作直接打開(kāi)項(xiàng)目根目錄下的project.config.json找到miniprogramRoot字段用相對(duì)路徑規(guī)則手動(dòng)驗(yàn)證一遍它指向的目錄下是否真有app.json。注意如果字段缺失工具默認(rèn)認(rèn)為小程序代碼就在項(xiàng)目根目錄這時(shí)你需要在根目錄放app.json或者補(bǔ)上這個(gè)字段。還要留個(gè)心眼從uni-app等框架生成的項(xiàng)目里miniprogramRoot有時(shí)候會(huì)帶上尾部斜杠src/有時(shí)候又不帶src工具處理相對(duì)路徑時(shí)對(duì)這兩種寫(xiě)法都能兼容真正決定成敗的是路徑本身是否存在。2.4 工具緩存導(dǎo)致的看不見(jiàn)文件排除完以上三個(gè)原因文件明明在指定位置、名字也對(duì)、路徑也正確但依然報(bào)錯(cuò)那就該懷疑開(kāi)發(fā)者工具自身的緩存和臨時(shí)索引了。微信開(kāi)發(fā)者工具在打開(kāi)項(xiàng)目的過(guò)程中會(huì)把工程結(jié)構(gòu)、文件列表、編譯中間產(chǎn)物緩存到本地一旦緩存與磁盤(pán)上的實(shí)際文件出現(xiàn)不一致就可能出現(xiàn)明明看到文件工具卻認(rèn)為它不存在的詭異狀態(tài)。這種狀態(tài)最典型的表現(xiàn)是在資源管理器和編輯器的文件樹(shù)里都能看到app.json雙擊也能正常打開(kāi)但控制臺(tái)編譯報(bào)錯(cuò)仍然是app.json未找到。解決辦法很簡(jiǎn)單——清除緩存后重新打開(kāi)。操作路徑菜單欄工具→清除緩存→清除文件緩存如果比較頑固就把編譯緩存和數(shù)據(jù)緩存也一并清掉然后關(guān)閉當(dāng)前項(xiàng)目窗口回到項(xiàng)目列表頁(yè)重新進(jìn)入。如果這樣還不行再進(jìn)一步關(guān)閉開(kāi)發(fā)者工具找到項(xiàng)目的本地緩存目錄在用戶(hù)目錄下不同版本路徑略有差異默認(rèn)形如C:\Users\你的用戶(hù)名\AppData\Local\微信開(kāi)發(fā)者工具\(yùn)把對(duì)應(yīng)項(xiàng)目名文件夾刪掉。這步相當(dāng)于讓工具忘記這個(gè)項(xiàng)目的所有歷史記憶下次導(dǎo)入時(shí)完全重新解析。要注意先備份因?yàn)檫@里偶爾會(huì)有編輯器的本地設(shè)置雖然大部分情況下只是緩存。我實(shí)測(cè)下來(lái)這一步能搞定90%以上的工具抽風(fēng)類(lèi)報(bào)錯(cuò)。3. 一套可以直接照做的排查鏈路從現(xiàn)象到根因3.1 第一步用新建項(xiàng)目做AB對(duì)照實(shí)驗(yàn)一個(gè)報(bào)錯(cuò)出來(lái)先不要埋頭在項(xiàng)目里翻來(lái)翻去。我習(xí)慣用AB對(duì)照法在五分鐘內(nèi)鎖定方向先新建一個(gè)官方提供的模板項(xiàng)目用同樣的工具、同樣的流程導(dǎo)入如果新項(xiàng)目能正常運(yùn)行說(shuō)明工具本身沒(méi)有大問(wèn)題問(wèn)題在原有項(xiàng)目如果新項(xiàng)目也報(bào)同樣的錯(cuò)誤說(shuō)明不是項(xiàng)目的問(wèn)題而是開(kāi)發(fā)者工具安裝、配置或權(quán)限層面的故障直接跳到重裝工具那一步。這個(gè)小實(shí)驗(yàn)的成本極低收益極高能幫你把排查范圍一下子砍掉一半。新建模板項(xiàng)目時(shí)留意一下在創(chuàng)建頁(yè)選擇小程序分類(lèi)下的JavaScript-基礎(chǔ)模板不要選云開(kāi)發(fā)模板因?yàn)樵崎_(kāi)發(fā)模板會(huì)自動(dòng)配置miniprogramRoot用它做AB實(shí)驗(yàn)反而容易掩蓋真實(shí)的根目錄問(wèn)題。3.2 第二步肉眼驗(yàn)證目錄結(jié)構(gòu)與真實(shí)文件名經(jīng)過(guò)第一步假設(shè)確認(rèn)是原項(xiàng)目的問(wèn)題。接下來(lái)打開(kāi)資源管理器定位到你在開(kāi)發(fā)者工具里填寫(xiě)的項(xiàng)目路徑重點(diǎn)做三件事第一確認(rèn)這個(gè)目錄是不是真的是小程序代碼根目錄——即目錄下第一層就有app.js、app.json、app.wxss三個(gè)文件。如果它們被包在嵌套目錄里說(shuō)明導(dǎo)入路徑選錯(cuò)了解決方法是重新導(dǎo)入選擇更里層的目錄或者在project.config.json里配置miniprogramRoot。第二確認(rèn)app.json的真實(shí)文件名。Windows下要點(diǎn)開(kāi)查看→顯示→文件擴(kuò)展名看看它到底叫app.json還是app.json.txt。這一步要連隱藏的系統(tǒng)文件一起顯示以防萬(wàn)一。我見(jiàn)過(guò)有人把APP.JSON這種全大寫(xiě)文件名當(dāng)成正常文件用在Windows資源管理器里看起來(lái)沒(méi)問(wèn)題Windows文件系統(tǒng)本身也不區(qū)分大小寫(xiě)但開(kāi)發(fā)者工具對(duì)文件名的匹配是精確匹配遇到大寫(xiě)文件名照樣報(bào)錯(cuò)。第三確認(rèn)app.json不是文件夾或者快捷方式。有人把桌面快捷方式拖進(jìn)了項(xiàng)目目錄或者用軟鏈接指到了別處工具讀取時(shí)會(huì)認(rèn)為文件不存在。右鍵查看屬性確保類(lèi)型顯示為JSON文件而不是快捷方式或文件夾。3.3 第三步檢查project.config.json的目錄指向第三步打開(kāi)項(xiàng)目根目錄的project.config.json用文本編輯器推薦VSCode純記事本容易在保存時(shí)引入中文編碼問(wèn)題查看miniprogramRoot字段。這一步驗(yàn)證邏輯很簡(jiǎn)單miniprogramRoot指向的目錄最終拼接出來(lái)要能定位到app.json。比如{ miniprogramRoot: miniprogram/ }這表示工具會(huì)到項(xiàng)目根目錄/miniprogram/下找app.json。如果這個(gè)字段寫(xiě)成了dist/而dist里并沒(méi)有app.json報(bào)錯(cuò)就順理成章。字段缺失時(shí)工具默認(rèn)是當(dāng)前根目錄也一并檢查。這步還有一個(gè)容易被忽略的細(xì)節(jié)project.config.json本身必須是合法JSON。文件內(nèi)容里如果多了一個(gè)逗號(hào)、注釋JSON官方格式不允許注釋但工具支持部分?jǐn)U展語(yǔ)法或者被保存成了帶BOM的UTF-8工具在讀取project.config.json階段就可能失敗表現(xiàn)之一就是無(wú)法正確解析miniprogramRoot進(jìn)而找不到app.json。3.4 第四步清理工具緩存與重新導(dǎo)入如果前三步都沒(méi)發(fā)現(xiàn)問(wèn)題進(jìn)入緩存清理環(huán)節(jié)。依次執(zhí)行開(kāi)發(fā)者工具菜單工具→清除緩存→全部清除文件緩存、編譯緩存、數(shù)據(jù)緩存都清一遍。關(guān)閉項(xiàng)目頁(yè)回到項(xiàng)目列表點(diǎn)擊項(xiàng)目卡片右下角...選擇移除項(xiàng)目這一步只是移除列表不會(huì)刪除磁盤(pán)文件然后重新通過(guò)導(dǎo)入項(xiàng)目添加。如果仍然報(bào)錯(cuò)徹底關(guān)閉開(kāi)發(fā)者工具打開(kāi)Windows的任務(wù)管理器確認(rèn)所有微信開(kāi)發(fā)者工具相關(guān)進(jìn)程都已結(jié)束再重新打開(kāi)工具并導(dǎo)入項(xiàng)目。養(yǎng)成這個(gè)先緩存、后移除、再導(dǎo)入的順序是因?yàn)殚_(kāi)發(fā)者工具對(duì)項(xiàng)目目錄的記住程度比我們想象得深。有些讀者在項(xiàng)目文件夾里改了很多東西但工具仍然按舊索引讀取這本質(zhì)上和瀏覽器緩存沒(méi)刷新是同一個(gè)道理。3.5 各階段癥狀與結(jié)論對(duì)照表為了讓你在排查時(shí)能快速對(duì)號(hào)入座我把上面各環(huán)節(jié)的癥狀和結(jié)論整理成一張表排查動(dòng)作看到的現(xiàn)象初步結(jié)論下一步操作新建模板項(xiàng)目導(dǎo)入新項(xiàng)目正常編譯工具環(huán)境正常問(wèn)題在項(xiàng)目進(jìn)入目錄結(jié)構(gòu)檢查新建模板項(xiàng)目導(dǎo)入新項(xiàng)目同樣報(bào)錯(cuò)工具/權(quán)限/環(huán)境故障清理全局緩存或重裝工具查看導(dǎo)入路徑下是否有app.json沒(méi)有目錄選錯(cuò)重新選擇正確根目錄或配置miniprogramRoot勾選顯示擴(kuò)展名實(shí)際文件名為app.json.txt文件名不對(duì)重命名為真正的app.json查看文件屬性類(lèi)型是快捷方式或文件夾文件類(lèi)型不符復(fù)制真實(shí)文件到項(xiàng)目目錄打開(kāi)project.config.jsonminiprogramRoot指錯(cuò)目錄路徑配置錯(cuò)誤改成正確相對(duì)路徑清理緩存后重進(jìn)報(bào)錯(cuò)消失緩存索引異常保持正常開(kāi)發(fā)節(jié)奏即可清理緩存后重進(jìn)報(bào)錯(cuò)依舊考慮工具版本/兼容問(wèn)題參考第六節(jié)重裝或調(diào)整版本這張表每次排查都可以直接照抄能省下不少來(lái)回試錯(cuò)的時(shí)間。4. Windows環(huán)境下的三個(gè)隱藏殺手編碼、權(quán)限與占用4.1 UTF-8編碼與BOM頭陷阱app.json是JSON文件必須是UTF-8編碼。Windows上最容易出現(xiàn)的問(wèn)題是用記事本編輯并保存文件時(shí)默認(rèn)編碼可能是ANSIGBK或帶BOM的UTF-8。GBK編碼保存的JSON對(duì)純英文內(nèi)容影響不大但一旦配置里寫(xiě)了中文比如tabBar的text、window的navigationBarTitleText工具按UTF-8解析時(shí)就會(huì)亂碼嚴(yán)重時(shí)直接判定文件內(nèi)容不可用報(bào)出文件內(nèi)容錯(cuò)誤。帶BOM的UTF-8更隱蔽。BOM是EF BB BF三個(gè)字節(jié)的文件頭許多Windows編輯器尤其記事本舊版本保存UTF-8時(shí)會(huì)自動(dòng)加上BOM。微信開(kāi)發(fā)者工具對(duì)BOM的容忍度在不同版本里都不一樣有的版本能自動(dòng)跳過(guò)有的則會(huì)把BOM讀入內(nèi)容導(dǎo)致JSON解析失敗。我驗(yàn)證過(guò)用記事本自帶功能另存為UTF-8Windows 10/11的記事本在另存為對(duì)話框中支持UTF-8與UTF-8帶BOM兩種選擇注意選不帶BOM的那個(gè)。如果你手頭文件已經(jīng)是GBK或帶BOM最穩(wěn)的處理方式是用VSCode打開(kāi)文件點(diǎn)擊右下角編碼信息選擇通過(guò)編碼重新打開(kāi)并選UTF-8然后保存時(shí)確保編碼是UTF-8且無(wú)BOM。VSCode默認(rèn)就是無(wú)BOM的UTF-8比記事本省心得多。4.2 只讀權(quán)限與殺毒軟件占用項(xiàng)目目錄被人為設(shè)置了只讀屬性或者NTFS權(quán)限里當(dāng)前用戶(hù)只有讀取權(quán)限而沒(méi)有寫(xiě)入權(quán)限開(kāi)發(fā)者工具在初始化時(shí)會(huì)嘗試往項(xiàng)目目錄寫(xiě)入臨時(shí)文件寫(xiě)不進(jìn)去就可能導(dǎo)致文件索引構(gòu)建異常。反映到報(bào)錯(cuò)上有時(shí)候就是app.json未找到。檢查方法是右鍵項(xiàng)目文件夾→屬性→檢查只讀欄是否打了勾取消之并點(diǎn)確定讓系統(tǒng)應(yīng)用到所有子文件夾。如果問(wèn)題在NTFS權(quán)限右鍵→屬性→安全選項(xiàng)卡→查看當(dāng)前用戶(hù)是否具備修改權(quán)限沒(méi)有就改一下或者把整個(gè)項(xiàng)目挪到自己的用戶(hù)目錄下比如C:\Users\你的用戶(hù)名\Projects。把項(xiàng)目放在C:\Program Files、C:\Program Files (x86)這類(lèi)系統(tǒng)目錄下是最容易觸發(fā)權(quán)限問(wèn)題的做法強(qiáng)烈不建議。殺毒軟件方面Windows Defender或第三方安全軟件有時(shí)會(huì)把工具掃描項(xiàng)目目錄視為異常行為鎖定正在讀取的文件。如果排除完其他所有原因還找不到問(wèn)題可以臨時(shí)關(guān)閉實(shí)時(shí)保護(hù)再導(dǎo)入一次注意這只是定位問(wèn)題不要為了開(kāi)發(fā)長(zhǎng)期關(guān)閉安全保護(hù)。更溫和的辦法是把項(xiàng)目目錄加入殺毒軟件的白名單/排除項(xiàng)。4.3 中文路徑、長(zhǎng)路徑與特殊字符路徑微信開(kāi)發(fā)者工具對(duì)中文路徑的支持時(shí)好時(shí)壞。同一個(gè)項(xiàng)目放在C:\Users\張三\Desktop\小程序項(xiàng)目里可能編譯正常放到C:\Users\張三\桌面\小程序【最終版】里就可能報(bào)各種奇怪錯(cuò)誤包括文件找不到。我自己的建議是項(xiàng)目目錄干脆全程使用英文、數(shù)字、連字符不要放中文和括號(hào)、井號(hào)、符號(hào)。這不是玄學(xué)底層是工具跨模塊路徑解析時(shí)對(duì)非ASCII字符和特殊字符的處理不夠統(tǒng)一既然改個(gè)路徑就能解決沒(méi)必要和工具較勁。長(zhǎng)路徑也是Windows經(jīng)典痛點(diǎn)。很多文件系統(tǒng)的默認(rèn)限制是260字符MAX_PATH當(dāng)項(xiàng)目嵌套層次深、目錄名又長(zhǎng)時(shí)文件完整路徑很容易超過(guò)這個(gè)長(zhǎng)度工具內(nèi)部調(diào)用文件系統(tǒng)API時(shí)就可能讀取失敗。解決辦法要么壓縮目錄深度要么在Windows注冊(cè)表中啟用長(zhǎng)路徑支持Win10 1607及以上版本可以做具體搜索啟用Win10長(zhǎng)路徑即可但即便如此我還是建議開(kāi)發(fā)用的項(xiàng)目路徑越短越好比如直接放在D:\work\myapp。5. 從Git倉(cāng)庫(kù)拉下來(lái)就報(bào)錯(cuò)的特殊場(chǎng)景5.1 .gitignore把a(bǔ)pp.json過(guò)濾了還有一種情況項(xiàng)目是本地的老項(xiàng)目一直能正常編譯。某天你或者同事把代碼推到Git倉(cāng)庫(kù)另一臺(tái)電腦上git clone下來(lái)一導(dǎo)入就報(bào)app.json未找到。如果目錄結(jié)構(gòu)看起來(lái)完全正?；究梢詰岩?gitignore配置把a(bǔ)pp.json給過(guò)濾掉了。為什么會(huì)出現(xiàn)這種操作我在實(shí)際項(xiàng)目里見(jiàn)過(guò)兩種典型寫(xiě)法誤傷app.json第一種是寫(xiě)了*.json想忽略所有JSON文件這種做法極其危險(xiǎn)會(huì)把package.json、tsconfig.json一起忽略第二種是團(tuán)隊(duì)里有人覺(jué)得app.json屬于構(gòu)建產(chǎn)物在.gitignore里加了app.json但app.json是小程序源碼的一部分是必須入庫(kù)的。出現(xiàn)這種情況后在Git倉(cāng)庫(kù)里執(zhí)行g(shù)it status git ls-files | grep app.json用第二條命令列出倉(cāng)庫(kù)中跟蹤的app.json相關(guān)文件。如果返回為空說(shuō)明app.json壓根沒(méi)被Git跟蹤。修復(fù)方式是在.gitignore里精確排除掉然后執(zhí)行g(shù)it add app.json重新納入版本管理。別忘了檢查其他小程序核心文件app.js、app.wxss、project.config.json、sitemap.json有沒(méi)有同樣被誤忽略。5.2 子模塊/單倉(cāng)庫(kù)多小程序目錄的場(chǎng)景公司里項(xiàng)目發(fā)展到一定規(guī)模后經(jīng)常用monorepo單倉(cāng)庫(kù)管理多個(gè)小程序。結(jié)構(gòu)類(lèi)似monorepo/ ├── packages/ │ ├── shop/ │ │ ├── app.js │ │ └── app.json │ └── admin/ │ ├── app.js │ └── app.json ├── project.config.json └── package.json這時(shí)候project.config.json的miniprogramRoot如果還停留在某個(gè)單獨(dú)小程序的相對(duì)路徑另一個(gè)小程序目錄下自然找不到app.json。處理方式有兩種一是每個(gè)小程序分別都有各自的project.config.json導(dǎo)入時(shí)選擇各自子目錄作為根目錄二是只在倉(cāng)庫(kù)根目錄保留一個(gè)project.config.json用miniprogramRoot指向當(dāng)前要開(kāi)發(fā)的那個(gè)小程序目錄但切換開(kāi)發(fā)目標(biāo)時(shí)記得同步修改。此外如果子模塊是通過(guò)git submodule拉取的而子模塊沒(méi)有正確初始化執(zhí)行過(guò)git submodule update --init那么對(duì)應(yīng)目錄在本地是空的里面的app.json自然不存在。遇到目錄看起來(lái)有但文件列表卻是空的的情況時(shí)優(yōu)先檢查子模塊狀態(tài)。Windows下還有個(gè)別情況是文件同步工具如OneDrive、堅(jiān)果云沒(méi)有把云端的文件完全同步到本地本地看到的只是占位符工具讀取時(shí)也會(huì)判定為文件不存在這個(gè)屬于Windows的按需同步文件File On-Demand特性把項(xiàng)目目錄從云同步目錄里移出來(lái)或者強(qiáng)制始終保留在此設(shè)備上即可。6. 最后再排掉工具本身的bug版本與基礎(chǔ)庫(kù)的配合問(wèn)題6.1 lib: 3.7.7基礎(chǔ)庫(kù)與工具版本兼容性報(bào)錯(cuò)信息里最后一段寫(xiě)的是(env: Windows, mp, 1.05.2204250 lib: 3.7.7)其中3.7.7是基礎(chǔ)庫(kù)版本號(hào)1.05.2204250是工具版本號(hào)。mp代表miniprogram小程序環(huán)境Windows是操作系統(tǒng)環(huán)境。整體來(lái)看這是工具在Windows下、針對(duì)小程序環(huán)境、使用3.7.7基礎(chǔ)庫(kù)進(jìn)行編譯時(shí)的報(bào)錯(cuò)?；A(chǔ)庫(kù)是微信客戶(hù)端里運(yùn)行小程序代碼的那套底層框架而開(kāi)發(fā)者工具會(huì)模擬這套環(huán)境。工具版本與基礎(chǔ)庫(kù)版本理論上各自獨(dú)立升級(jí)但在某些過(guò)渡版本里會(huì)有兼容性問(wèn)題。如果你把項(xiàng)目里project.config.json的libVersion配置得很高例如3.8.x或4.x而開(kāi)發(fā)者工具版本還停留在1.05系列工具對(duì)高版本基礎(chǔ)庫(kù)的支持可能不完整進(jìn)而引發(fā)文件加載、解析層面的錯(cuò)亂。處理辦法打開(kāi)project.config.json找到libVersion字段把它改成當(dāng)前工具能穩(wěn)定支持的基礎(chǔ)庫(kù)版本通常官方發(fā)布新版工具時(shí)會(huì)公告對(duì)應(yīng)的最低/推薦基礎(chǔ)庫(kù)版本或者直接在工具的詳情→本地設(shè)置里調(diào)整調(diào)試基礎(chǔ)庫(kù)版本選一個(gè)更低的穩(wěn)定版本再試。如果改完版本后報(bào)錯(cuò)消失就說(shuō)明是版本間配合問(wèn)題。6.2 工具重裝與降級(jí)處理如果以上所有嘗試都無(wú)效最后的手段是重裝微信開(kāi)發(fā)者工具。這和普通軟件重裝不一樣的地方在于不要急著卸載新版裝回舊版先完整卸載當(dāng)前版本手動(dòng)刪除安裝目錄和用戶(hù)緩存目錄C:\Users\你的用戶(hù)名\AppData\Local\微信開(kāi)發(fā)者工具重啟電腦后再重新安裝。選版本時(shí)留意最新的穩(wěn)定版不一定是最穩(wěn)的。微信開(kāi)發(fā)者工具每個(gè)月都有新版本推送部分開(kāi)發(fā)版Preview版多多少少帶著實(shí)驗(yàn)性功能穩(wěn)定性欠佳。如果你正在做的是公司正式項(xiàng)目建議使用穩(wěn)定版Stable或者停留在團(tuán)隊(duì)里多數(shù)人驗(yàn)證過(guò)的某個(gè)版本。不同機(jī)器上工具版本不一致時(shí)同一項(xiàng)目可能會(huì)表現(xiàn)出不同行為這也是團(tuán)隊(duì)協(xié)作中一個(gè)隱蔽的變量。重裝后導(dǎo)入項(xiàng)目時(shí)額外注意如果原本是通過(guò)導(dǎo)入項(xiàng)目→從Git導(dǎo)入的方式會(huì)額外拉取Git倉(cāng)庫(kù)重裝后依然走這個(gè)流程如果原本是普通的目錄導(dǎo)入直接選擇原目錄即可。由于緩存目錄已經(jīng)刪掉工具會(huì)用一種全新的視角重新解析項(xiàng)目目錄之前因?yàn)榫彺媾で鷮?dǎo)致的app.json未找到通常會(huì)在這一步迎刃而解。如果你是按順序走完上面這些步驟才看到這里大概率已經(jīng)把問(wèn)題解決了。根據(jù)我自己的經(jīng)驗(yàn)至少七成類(lèi)似報(bào)錯(cuò)卡在第一類(lèi)——項(xiàng)目根目錄選錯(cuò)兩成卡在Windows的文件擴(kuò)展名顯示真正需要重裝工具才能解決的反而少見(jiàn)。排查時(shí)不用慌先從目錄和文件名兩個(gè)最基礎(chǔ)的維度下手比任何高級(jí)操作都好使。如果非要再分享一條個(gè)人習(xí)慣我會(huì)每隔一段時(shí)間把項(xiàng)目里的project.config.json打開(kāi)看一眼確認(rèn)miniprogramRoot和libVersion沒(méi)被莫名改動(dòng)這個(gè)文件雖然小卻是工具和項(xiàng)目之間最關(guān)鍵的接頭暗號(hào)。希望下次你再看到這個(gè)刺眼的紅色報(bào)錯(cuò)時(shí)已經(jīng)有條不紊不再手忙腳亂。