HTML 註釋不會在瀏覽器畫面顯示,僅存在於原始碼中,是開發者溝通、除錯、文件化的重要工具。本文完整整理註釋語法、條件註釋、CSS/JS 註釋差異、最佳實務與避坑指南。
<!-- 這是單行註釋 -->
<!--
這是多行註釋
可以跨越多行
結尾必須是 -->
-->
<!-- 開頭,--> 結尾。-- (除開頭結尾),否則會提前結束或解析錯誤。<div <!-- 注釋 --> class="box"> 合法但不建議)。用於針對舊版 IE 載入修補樣式/腳本,**現代專案已無需使用** (IE 於 2022/6/15 終止支援)。
<!--[if IE]>
<link rel="stylesheet" href="ie-fix.css">
<![endif]-->
<!--[if lt IE 9]>
<script src="html5shiv.js"></script>
<![endif]-->
<!--[if !IE]>> <!-- 非 IE 瀏覽器執行 -->
<link rel="stylesheet" href="modern.css">
<!--<![endif]-->
語法說明: [if IE], [if lt IE 9] (小於 IE9), [if gte IE 10] (IE10+), [if !IE] (非 IE)。
| 語言 | 單行註釋 | 多行註釋 | 可巢狀 |
|---|---|---|---|
| HTML | <!-- 註釋 --> | <!-- 多行 --> | 否 |
| CSS | 無單行語法 | /* 註釋 */ | 否 (標準 CSS),支援於 Sass/Less/PostCSS |
| JavaScript | // 註釋 | /* 註釋 */ | 否 (標準 JS),TypeScript/JSDoc 另有文檔註釋 |
<header class="site-header">
...
</header>
<!-- /site-header -->
<main class="main-content">
<article class="post">
...
</article>
<!-- /post -->
</main>
<!-- /main-content -->
巢狀結構深時,結尾註釋能快速對應開始標籤,減少心智負擔。
<!-- === Hero Section === -->
<section class="hero">...</section>
<!-- === Features Grid === -->
<section class="features">...</section>
<!-- TODO: 優化圖片載入策略 -->
<!-- FIXME: IE11 flexbug 處理 -->
<!-- HACK: 覆蓋第三方組件樣式 -->
<!-- NOTE: 此處依賴全域變數 window.APP_CONFIG -->
<!--
<div class="promo-banner">...</div>
<script src="legacy-tracker.js"></script>
-->
注意: 被註釋代碼若包含 <!-- ... --> 會導致外層註釋提前結束。建議使用編輯器「切換註釋」功能 (VS Code: Ctrl+/ / Cmd+/) 自動處理,或改用版本控制 (Git) 刪除/恢復代碼。
<!-- 這會輸出到 DOM --> vs <!-- @TODO 這不會輸出 (需配置) -->{/* 註釋 */} (不輸出 DOM),HTML 註釋在 JSX 中需寫 {'<!-- 註釋 -->'}。{{! 註釋 }} (不輸出),<!-- {{! 註釋 }} --> (輸出 HTML 註釋)。{# 註釋 #} (不輸出)。| 錯誤 | 後果 | 修正 |
|---|---|---|
<!-- -- 連續連字號 --> | 解析錯誤、後續內容可能被誤判為註釋 | 避免內容含 --,改用 == 或空格分隔 |
巢狀註釋 <!-- outer <!-- inner --> outer --> | 內層結尾關閉外層,外層剩餘內容外洩 | 勿巢狀,用版本控制管理代碼版本 |
註釋包含 > 字元 | 舊版瀏覽器可能誤判結尾 | 避免在註釋寫類 HTML 片段,或用編碼 > |
在 <title>, <style>, <script> 內用 HTML 註釋 | 不生效或語法錯誤 | 用該語言原生註釋 (CSS: /* */, JS: ////* */) |
| 生產環境保留大量 TODO/FIXME/HACK 註釋 | 洩露內部資訊、增加傳輸體積 | 建構流程移除註釋 (HTMLMinifier, terser 等) |
部署上線前,建議移除 HTML 註釋以減少檔案體積、避免資訊洩露:
html-minifier --remove-comments --collapse-whitespace -o dist/index.html src/index.htmlHtmlWebpackPlugin 選項 minify: { removeComments: true }html.minify (採用 html-minifier-terser)。<!--[if IE]> 若需保留給極少數舊環境,配置 removeComments: { safe: true } 保留以 ! 開頭的註釋。<!-- 內容 -->,不可巢狀,禁連續 --。良好的註釋習慣,是代碼可維護性的基石,也是團隊協作的潤滑劑。