使用說明

YAML lint 檢查:邊輸入邊找出語法問題

貼上你的 YAML,這個 YAML lint 工具會在你輸入時檢查,並用簡單的話說明每個語法問題,附上行號與欄位。它能找出以 Tab 縮排、重複的鍵、沒有關閉的引號與括號,以及看起來像縮排、其實不是的隱形不換行空格。你的 YAML 只會在你的瀏覽器內檢查,不會上傳。


YAML 檢查器的使用步驟

把 YAML 貼到 YAML 欄位,或直接在裡面輸入。沒有驗證按鈕:文字會即時檢查。

  1. 貼上的文字會立刻檢查。輸入時,檢查會在你按下最後一個鍵後約四分之一秒啟動,文字非常大時會稍慢一點。新結果出現前,上一個結果會維持淡化顯示。
  2. 看編輯器下方的方框。綠色的 YAML 有效 方框代表語法正確。紅色的「YAML 無效」方框(或「YAML 無效:N 個問題」)會列出哪裡有問題。
  3. 每個問題都有一句說明、「第 N 行,第 M 欄」,以及附行號的該行片段:上方兩行、下方一行,並在欄位下方標出 ^。
  4. 按下 在編輯器中顯示,就會在欄位中選取那一行。修正之後,方框會轉為綠色。

每份內容只會回報第一個語法錯誤。後面的錯誤通常是連帶影響,例如少了一個引號,把下面的行都吞掉了。重複的鍵和未定義的別名一律全部列出,最多顯示 20 個問題。

YAML 檢查常見問題與修正方法

每個問題都用一句話說明,而不是剖析器的原始訊息。以下是最常遇到的:

其他工具的錯誤訊息是什麼意思

你是看了終端機或 CI 記錄中的訊息才來到這裡嗎?下面列出常見說法和這個工具所回報內容的對應。貼上同一個檔案,就能看到是哪一行。

不同剖析器(PyYAML、js-yaml、Ruby、Go、Home Assistant 與 ESPHome 的載入器)的說法不同,剖析器也常常回報真正錯誤下方的那一行。這個工具會指出它能顯示給你的那一行。

Tab 與隱形字元的檢查

YAML 最難發現的兩種錯誤,是看不見的那種。這個工具會讓它們現形。

舉例:在含有 server:,下面是 port: 8080 的檔案中,最後一行 host: example.com 開頭是兩個不換行空格,而不是兩個一般空格。YAML 會把它讀成另一個最上層的鍵,host 就不是 server 的子項。黃色方框會指出那個字元和那一行。

YAML 格式化與複製結果

打開欄位上方的 格式化 YAML 開關。預設是關閉的。文字有效時,會出現 格式化後的 YAML 區塊,上方有 複製 按鈕,複製後會變成 已複製。格式化的結果可以預期:

只有有效的 YAML 才能格式化,所以它無法修復壞掉的檔案:請先修正錯誤。非常長的輸出會在 600,000 個字元後截斷顯示,但複製仍然會複製全部內容。

YAML 格式檢查的用途、大小與限制

無論 YAML 用在什麼地方,檢查方式都相同。它適用於 GitHub Actions 工作流程、docker-compose.yml、Kubernetes 資訊清單與 Helm 值、OpenAPI 檔案、Ansible playbook、Home Assistant 設定、CloudFormation 範本和 mkdocs 設定。在提交之前貼上檔案,不必等 CI 執行就能看到語法錯誤。含有多份以 --- 分隔內容的檔案,會逐份檢查,綠色方框會顯示找到幾份。錨點(&名稱)與別名(*名稱)也會檢查,上方沒有錨點的別名會被回報。CloudFormation 的 !Ref、!Sub、!GetAtt,或 GitLab 的 !reference 這類自訂標籤會被視為有效。

檢查在你瀏覽器的 Web Worker 中執行。一般的設定、CI 和 Kubernetes 檔案轉眼就能檢查完。上限是 5,000,000 個字元,接近上限的文字需要幾秒鐘,也會用掉很多記憶體。超過上限時,會請你貼上較小的片段。

只檢查 YAML 語法。它不知道特定工具期待什麼,所以 Kubernetes 欄位、GitHub Actions 或 Docker Compose 的鍵,以及 JSON Schema 規則都不會檢查,拼錯的鍵名也照樣通過。它遵循 YAML 1.2,因此 YAML 1.1 的 yes、no、on、off 只是普通文字,不會被判斷。它不會執行、擷取或載入任何東西,單獨出現的舊式 Mac 歸位字元也不會被視為換行。

要處理其他格式嗎?用 JSON格式化工具 整理並檢查 JSON,用 JSON Schema 驗證器 對照結構描述,或用 XML 驗證器 檢查標記。想在設定中比對某個模式?可以在 正規表達式測試工具 裡試試。


常見問題

要怎麼做 YAML lint 檢查?

把 YAML 貼到「YAML」欄位。貼上或輸入時就會檢查,所以沒有按鈕可按。綠色的「YAML 有效」方框代表語法正確。紅色的「YAML 無效」方框會用簡單的話列出每個問題,附上「第 N 行,第 M 欄」和該行的片段。

為什麼 YAML 說縮排不能使用 Tab?

YAML 的縮排只能用空格,行首的 Tab 是語法錯誤。編輯器在你按 Tab 鍵時常會插入 Tab,貼上的文字也可能帶有 Tab。這個工具會指出那一行是用 Tab 縮排的。請把 Tab 換成空格。

YAML 的 mapping values are not allowed here 是什麼意思?

通常是同一行出現第二個冒號,例如「a: b: c」,或是沒有引號的值中含有冒號。也可能是在已經有值的鍵底下縮排了一行。請把值放在引號中,或把內層的配對寫在自己的縮排行。

YAML 的 did not find expected key 是什麼意思?

某一行沒有和同一個對應中的其他鍵對齊。通常是某個鍵比旁邊的鍵多或少一個空格。請讓同一層的所有鍵使用相同的縮排。這個工具會回報那一行沒有和其他鍵對齊。

要怎麼找出 YAML 中重複的鍵?

貼上文字即可。同一個對應中重複的鍵一律全部列出,每個都附行號與欄位。通常是複製的區塊留下了重複的鍵。請合併,或刪除重複的那個。

為什麼有效的 YAML 會顯示「有效,但請檢查這幾行」?

某一行以隱形空格開頭,例如不換行空格。YAML 會把它當成鍵的一部分,所以即使檔案有效,那一行其實也沒有縮排。黃色方框會指出那個字元和那一行。請刪除它,改輸入一般空格。

可以在這裡檢查 GitHub Actions、Docker Compose 或 Kubernetes 的 YAML 嗎?

可以,任何 YAML 的語法檢查都一樣。它適用於工作流程、docker-compose.yml、Kubernetes 資訊清單和許多其他檔案。只檢查語法:它不知道各工具期待哪些鍵,拼錯的鍵名也照樣通過。

YAML 檔案最大可以檢查多大?

上限是 5,000,000 個字元。一般的設定檔轉眼就能檢查完,接近上限的文字需要幾秒鐘,也會用掉很多記憶體。超過上限時,會請你貼上較小的片段。