JSON 可以寫註解嗎
結論：RFC 8259 沒有註解語法，`//` 與 `/* */` 都會讓 JSON.parse 直接拋錯。要寫說明只有四條路：改用 JSON5/JSONC、把備註塞進資料欄位、寫進 Schema 的 description，或改用 YAML。
結論：標準 JSON 裡不要寫註解；只給人編輯的本機設定改用 JSONC 或 JSON5，要跨系統傳輸時把說明搬進 JSON Schema 的 description，註解量大就直接換 YAML 或 TOML。
不行。
在任何標準 JSON 解析器裡，下面這段都會拋錯：
{
"port": 8080 // 本機開發用這個埠
}
瀏覽器主控台給的訊息是 SyntaxError: Unexpected token }——註解被當成非法字元，解析器讀到 / 就停下來了。
標準為什麼刻意不留註解
RFC 8259 的語法只有六種值：物件、陣列、數字、字串、true/false、null，沒有任何註解產生式。
早期確實有人提議要加，反對的理由很實際：註解一旦合法，就會有人拿它放解析指令，例如條件包含、範本變數，於是每個解析器都要實作自己的方言，跨語言互換立刻失效。JSON 的定位是「資料就是資料」，把可執行的語意擋在門外。
所以註解不是「沒人做」，而是「有意不做」。
想寫說明，四條路可選
第一條：改用 JSON5 或 JSONC。 這兩個都是超集，//、/* */ 都支援，VS Code 的 settings.json、tsconfig.json 走的就是 JSONC。
代價很清楚：JSON.parse 依然不認，介面、日誌、訊息佇列通常只吃標準 JSON，註解會在傳輸鏈路的某一環被吃掉或直接報錯。
第二條：把備註塞進資料。 常見寫法是加一個 _comment 或 _note 鍵：
{
"_comment": "埠由維運統一分配，勿改",
"port": 8080
}
代價是汙染資料模型，消費方必須知道要跳過哪些鍵，型別定義也要跟著多一個欄位。
第三條：寫進 JSON Schema。 description 本來就是給人和工具讀的，驗證器能輸出它，IDE 能顯示它，而它不進入資料本身。這是唯一既能長期維護、又不破壞相容性的做法。
第四條：換設定檔格式。 如果這份檔案天生就是給人改的，YAML 和 TOML 支援註解，比硬撐 JSON 更省事。
怎麼判斷該走哪條
| 情境 | 結論 |
|---|---|
| 要傳給外部系統、走介面、進訊息佇列 | 不能註解，說明寫進 Schema 或文件 |
| 只給人和編輯器看的設定 | 用 JSONC，別硬塞進 .json |
| 需要工具鏈全相容，又要保留說明 | 標準 JSON + Schema description |
| 設定檔很長、註解很多 | 直接換 YAML |
常見問題
為什麼 _comment 欄位會汙染資料模型？
因為它進入了資料本身。消費方必須知道要跳過哪些鍵，型別定義也要多出一個並非真實業務的欄位。
是否能把說明寫進 JSON Schema？
可以，而且這是唯一既能長期維護、又不破壞相容性的做法。description 不進入資料，驗證器能輸出它，IDE 也能顯示它。
JSONC 和 JSON5 能否直接交給 JSON.parse？
不能。JSON.parse 依然不認註解，介面、日誌和訊息佇列通常只吃標準 JSON，註解會在鏈路的某一環被吃掉或直接報錯。
相關工具
- JSON5 解析器：把帶註解的設定貼進去，看解析後到底是什麼結構
- JSON 格式化與驗證：非法 JSON 會定位到具體行列，註解寫在哪一行一眼能看出來