YAML lint 檢查:邊輸入邊找出語法問題
貼上你的 YAML,這個 YAML lint 工具會在你輸入時檢查,並用簡單的話說明每個語法問題,附上行號與欄位。它能找出以 Tab 縮排、重複的鍵、沒有關閉的引號與括號,以及看起來像縮排、其實不是的隱形不換行空格。你的 YAML 只會在你的瀏覽器內檢查,不會上傳。
YAML 檢查器的使用步驟
把 YAML 貼到 YAML 欄位,或直接在裡面輸入。沒有驗證按鈕:文字會即時檢查。
- 貼上的文字會立刻檢查。輸入時,檢查會在你按下最後一個鍵後約四分之一秒啟動,文字非常大時會稍慢一點。新結果出現前,上一個結果會維持淡化顯示。
- 看編輯器下方的方框。綠色的 YAML 有效 方框代表語法正確。紅色的「YAML 無效」方框(或「YAML 無效:N 個問題」)會列出哪裡有問題。
- 每個問題都有一句說明、「第 N 行,第 M 欄」,以及附行號的該行片段:上方兩行、下方一行,並在欄位下方標出 ^。
- 按下 在編輯器中顯示,就會在欄位中選取那一行。修正之後,方框會轉為綠色。
每份內容只會回報第一個語法錯誤。後面的錯誤通常是連帶影響,例如少了一個引號,把下面的行都吞掉了。重複的鍵和未定義的別名一律全部列出,最多顯示 20 個問題。
YAML 檢查常見問題與修正方法
每個問題都用一句話說明,而不是剖析器的原始訊息。以下是最常遇到的:
- 這一行用 Tab 縮排。編輯器插入了 Tab,或是貼上時一起帶進來。請把 Tab 換成空格。
- 這一行沒有和同一個對應(mapping)中的其他鍵對齊。某個鍵比旁邊的鍵多或少一個空格。請讓同一層的鍵使用相同的縮排。
- 縮排不正確。巢狀區塊的縮排沒有比上一層更深。請讓子項比父層的鍵縮得更深。
- 同一個對應中有重複的鍵。通常是複製的區塊留下了重複的鍵。請合併,或刪除重複的那個。
- 這一行不是「鍵: 值」的配對。少了冒號,或是換行後的內容沒有縮排。請在鍵後面加上
:,或把接續的行縮排。 - 同一行中,一組配對寫在另一組配對裡面。通常是一般的值裡出現第二個冒號,例如
a: b: c。請把值放在引號中,或改用新的縮排行。 - 括號一直沒有關閉,或引號沒有結束。訊息會指向開啟的那一行。請補上結尾的符號。
[ ]或{ }內的項目之間少了逗號。兩個項目黏在一起。請補上逗號。- 值以
@或反引號開頭。請把值放在引號中。 #黏在前一個字後面。前面要有空格才會開始註解。請補上空格,或把文字放在引號中。\q在雙引號中不是有效的跳脫字元。Windows 路徑常出現這種情況。請寫成\\,或改用單引號。- 別名指向上方沒有定義的錨點。請在檔案前面定義
&名稱。 - 這一部分放在這裡不合適。常見原因是以
-開頭的清單和「鍵: 值」的行在同一層混用,或上一行沒寫完。請把清單放在自己的鍵底下,並檢查上一行。 - 內容開頭的
%指令無效或不支援。請移除它,或正確使用%YAML或%TAG。
其他工具的錯誤訊息是什麼意思
你是看了終端機或 CI 記錄中的訊息才來到這裡嗎?下面列出常見說法和這個工具所回報內容的對應。貼上同一個檔案,就能看到是哪一行。
found character that cannot start any token while scanning for the next token:行首的 Tab,或是以@或反引號開頭的值。tabs are not allowed for indent:用 Tab 當縮排。mapping values are not allowed here:同一行出現第二個冒號(例如a: b: c)、沒有引號的值中含有:,或是在已經有值的鍵底下縮排了一行。did not find expected key:沒有和同一個對應中其他鍵對齊的行。bad indentation of a mapping entry:縮排深度不對的鍵。could not find expected ':':鍵後面沒有冒號的行。
不同剖析器(PyYAML、js-yaml、Ruby、Go、Home Assistant 與 ESPHome 的載入器)的說法不同,剖析器也常常回報真正錯誤下方的那一行。這個工具會指出它能顯示給你的那一行。
Tab 與隱形字元的檢查
YAML 最難發現的兩種錯誤,是看不見的那種。這個工具會讓它們現形。
- 片段中的 Tab 會畫成箭頭,不換行空格或零寬空格會畫成圓點。
- 如果有錯誤的那一行含有隱形字元,會多一行說明它的名稱與碼位(例如
U+00A0)以及欄位。涵蓋不換行空格、零寬字元、位元組順序標記和全形空格。 - 檔案有效,但某一行以隱形空格開頭時,綠色方框下方會出現黃色的 有效,但請檢查這幾行 方框。YAML 會把那個字元當成鍵的一部分,所以那一行其實沒有縮排。從網頁、wiki 或聊天軟體複製的文字,是最常見的來源。
舉例:在含有 server:,下面是 port: 8080 的檔案中,最後一行 host: example.com 開頭是兩個不換行空格,而不是兩個一般空格。YAML 會把它讀成另一個最上層的鍵,host 就不是 server 的子項。黃色方框會指出那個字元和那一行。
YAML 格式化與複製結果
打開欄位上方的 格式化 YAML 開關。預設是關閉的。文字有效時,會出現 格式化後的 YAML 區塊,上方有 複製 按鈕,複製後會變成 已複製。格式化的結果可以預期:
- 縮排是 2 個空格。沒有其他寬度,鍵底下的清單會縮排。
- 註解、錨點、別名、引號樣式和鍵的順序都會保留。
- 過長的行絕不會換行。
- 多份內容會保留各自的
---分隔線。
只有有效的 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 個字元。一般的設定檔轉眼就能檢查完,接近上限的文字需要幾秒鐘,也會用掉很多記憶體。超過上限時,會請你貼上較小的片段。