開發者工具 · JSON 格式化程式和驗證程序
在 CI 之前修復損壞的 package.json：讀取錯誤位置
· 為什麼它很重要
json 開發人員工作流程 驗證
手動編輯的 package.json、composer.json 或 launch.json 在儲存後很久就會失敗（通常在 CI 中）。這篇文章展示瞭如何在提交之前進行驗證並快速讀取錯誤位置。
十二分鐘的管道來了解一個逗號
十二分鐘的管道來了解一個逗號 - 手動解決合併衝突，綠色編輯器和紅色構建。儲存庫簽出看起來很正常，因為 Git 記錄的是字節，而不是清單是否解析。然後 CI 安裝依賴項、到達損壞的檔案並在測試提供任何有用訊號之前停止。
此工具只檢查嚴格的 JSON 語法，並接受最多 8,000,000 JavaScript 字元的檔案。 package.json 和composer.json 是合適的嚴格範例。 tsconfig.json 等檔案可能使用註解容忍解析器，因此拒絕它們的註解作為 JSON 並不能證明擁有工具會拒絕它們。根據使用程序實際宣告的語法進行驗證。
哪個 JSON 設定檔最常損壞
哪些 JSON 設定檔最常損壞 - package.json、composer.json、launch.json 和鎖定檔案，以及為什麼允許註解的 tsconfig.json 需要單獨處理。人工編輯的清單往往會因依賴區塊、腳本和巢狀工具設定而失敗。產生的鎖定檔案會以不同的方式失敗：手動解決衝突可能會損壞分隔符號或重複的結構部分。
不要假設每個具有類似 JSON 副檔名的檔案都使用嚴格的 JSON。 VS Code 設定和 TypeScript 配置通常允許透過專門的解析器進行註解或尾隨逗號，而套件清單通常不允許。盡可能使用套件管理器驗證產生的鎖定檔案，因為僅有效語法無法恢復該產生器所期望的雜湊、排序規則或內部一致性。
為什麼工具會遲到失敗 - 套件管理器和編譯器按需解析，因此在安裝或建置時而不是在儲存時出現語法錯誤
為什麼工具會遲到失敗 - 套件管理器和編譯器按需解析，因此語法錯誤在安裝或建置時而不是在儲存時出現。文字編輯器可以在不執行權威解析器的情況下為大括號著色，並在狹窄的本地任務期間可能無法讀取更改的清單。 CI 從乾淨的環境開始，並練習快取工作站跳過的設定路徑。
由此產生的延遲包括佇列時間、結帳時間、依賴關係設定和不相關的初步作業。更糟的是，最終的訊息可能僅命名無效的套件檔案，而將原始行隱藏在命令輸出後面。編輯後立即進行本機解析會破壞該回饋循環。它還將語法錯誤與後來需要不同調查的依賴關係解析或模式錯誤分開。
讀取壓力下的錯誤位置
在壓力下讀取錯誤位置 — 行和列、前一個標記以及產生無效 JSON 的三個合併衝突模式。標記的字元是不可能繼續的地方，而不總是錯誤開始的地方。收盤報價可能會暴露較早的未轉義報價；大括號可能會顯示下一個屬性之前缺少的逗號。
合併後，尋找保留為純文字的衝突標記、不使用逗號連接的重複成員區塊以及在選擇一側時刪除的分隔符號。檢查報告位置之前的令牌並計算周圍的容器邊界。進行一次修復，重新執行驗證並保留原始差異，因為解析器通常只報告第一個障礙，而第二個獨立衝突可能會保留在更遠的位置。
工作範例：錯誤合併後的 package.json
工作範例：錯誤合併後的 package.json — 重複的依賴項區塊、缺少逗號、驗證器報告和修復。想像一下 `"scripts":{"test":"vitest"}` 緊接而來的是 `"dependencies":{"vite":"7.3.6"}`。第二個屬性名稱是解析器發現物件缺少分隔符號的地方，儘管修正逗號屬於腳本物件之後。
插入該逗號並在格式化之前再次驗證。如果合併也產生了兩個 `dependencies` 鍵，則嚴格解析仍可能成功，因為語法上允許重複名稱，但 JavaScript 解析僅保留後面的值。比較兩個分支並合併預期的成員，而不是機械地刪除區塊。語法修復和語意合併解析是連續的、不同的任務。
讓驗證成為一種習慣
讓驗證成為一種習慣 - 在提交之前貼上，或驗證您在 IDE 外部編輯的任何 JSON，無需帳戶或插件。最好的觸發因素是行為：每當解決衝突標記、移動大塊或手動輸入標點符號時，在暫存檔案之前執行所屬工具的檢查或嚴格的解析器。
儲存庫可以透過預先提交檢查和清單範圍內的 CI 作業自動化相同的規則，但自動化應該補充即時回饋，而不是成為第一個解析器。將格式化與修復分開，以便差異顯示有意義的字元。對於產生的檔案，從來源清單重新產生，而不是標準化手動編輯的輸出，然後讓產生器證明其自身的不變量。
這不包括什麼
這不包括 - 語義錯誤，例如錯誤的版本範圍或未知欄位，有效的 JSON 無法保護您免受這些錯誤的影響。套件清單可以在命名不存在的腳本時進行解析，將依賴項放入錯誤的部分或使用意外解析的版本表達式。重複的鍵也可以通過語法檢查，同時默默地替換較早的值。
使用套件管理器驗證、模式、安裝測試並審查這些層。此檢查也不能證明鎖定檔案與其清單匹配，也不能證明啟動配置命名了已安裝的偵錯器。如果實際格式是 JSONC 或其他方言，請使用其解析器，而不是僅僅為了滿足嚴格的 JSON 而刪除支援的語法。語法是最早的門，而不是完整的配置合約。
重點：語法檢查需要幾秒鐘，失敗的管道需要幾分鐘
重點：語法檢查需要幾秒鐘的時間，失敗的管道需要幾分鐘的時間 - 並驗證器的精確報告縮短了修復時間。在最終編輯的位元組上執行它，從報告的行和列開始，然後檢查前面的標記是否缺少分隔符號或定界符。每次更正後重新驗證，因為後來的錯誤最初可以被隱藏。
一旦嚴格的語法通過，傳回給使用者：執行套件管理器、編譯器或編輯器特定的驗證來瞭解允許的欄位和值。保持修復差異較小，尤其是在合併之後，以便審查者可以區分標點符號和依賴性決策。此序列在本地捕獲最便宜的故障，並為只有完整環境才能評估的行為保留昂貴的管道時間。