萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網頁製作 >> HTML5 教學

HTML 註釋語法完整指南:基本格式、條件註釋、最佳實務與常見錯誤

HTML 註釋不會在瀏覽器畫面顯示,僅存在於原始碼中,是開發者溝通、除錯、文件化的重要工具。本文完整整理註釋語法、條件註釋、CSS/JS 註釋差異、最佳實務與避坑指南。

1. 基本 HTML 註釋語法

<!-- 這是單行註釋 -->

<!--
  這是多行註釋
  可以跨越多行
  結尾必須是 -->
-->

核心規則

  • 以 <!-- 開頭,--> 結尾。
  • 註釋內容不可包含兩個連續連字號 -- (除開頭結尾),否則會提前結束或解析錯誤。
  • 不可巢狀註釋 (註釋裡不能再包註釋)。
  • 註釋可置於標籤之間、屬性值中 (罕見)、標籤內部 (如 <div <!-- 注釋 --> class="box"> 合法但不建議)。

2. 條件註釋 — 僅 IE 5-9 支援 (歷史參考)

用於針對舊版 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)。

3. CSS 與 JavaScript 註釋語法差異

語言單行註釋多行註釋可巢狀
HTML<!-- 註釋 --><!-- 多行 -->否
CSS無單行語法/* 註釋 */否 (標準 CSS),支援於 Sass/Less/PostCSS
JavaScript// 註釋/* 註釋 */否 (標準 JS),TypeScript/JSDoc 另有文檔註釋

4. 實用註釋模式與最佳實務

區塊結構標示 (強烈建議)

<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) 刪除/恢復代碼。

模板引擎/框架中的註釋

  • Vue: <!-- 這會輸出到 DOM --> vs <!-- @TODO 這不會輸出 (需配置) -->
  • React (JSX): {/* 註釋 */} (不輸出 DOM),HTML 註釋在 JSX 中需寫 {'<!-- 註釋 -->'}。
  • Handlebars: {{! 註釋 }} (不輸出),<!-- {{! 註釋 }} --> (輸出 HTML 註釋)。
  • Jinja2/Django: {# 註釋 #} (不輸出)。

5. 常見錯誤與避坑

錯誤後果修正
<!-- -- 連續連字號 -->解析錯誤、後續內容可能被誤判為註釋避免內容含 --,改用 == 或空格分隔
巢狀註釋 <!-- outer <!-- inner --> outer -->內層結尾關閉外層,外層剩餘內容外洩勿巢狀,用版本控制管理代碼版本
註釋包含 > 字元舊版瀏覽器可能誤判結尾避免在註釋寫類 HTML 片段,或用編碼 &gt;
在 <title>, <style>, <script> 內用 HTML 註釋不生效或語法錯誤用該語言原生註釋 (CSS: /* */, JS: ////* */)
生產環境保留大量 TODO/FIXME/HACK 註釋洩露內部資訊、增加傳輸體積建構流程移除註釋 (HTMLMinifier, terser 等)

6. 生產環境優化:移除註釋

部署上線前,建議移除 HTML 註釋以減少檔案體積、避免資訊洩露:

  • HTMLMinifier / html-minifier-terser : html-minifier --remove-comments --collapse-whitespace -o dist/index.html src/index.html
  • Webpack : HtmlWebpackPlugin 選項 minify: { removeComments: true }
  • Vite : 內建 html.minify (採用 html-minifier-terser)。
  • 注意: 條件註釋 <!--[if IE]> 若需保留給極少數舊環境,配置 removeComments: { safe: true } 保留以 ! 開頭的註釋。

總結

  • HTML 註釋:<!-- 內容 -->,不可巢狀,禁連續 --。
  • 善用結構標示、TODO/FIXME、區隔區塊,提升代碼可讀性。
  • 區分 HTML/CSS/JS 註釋語法,框架模板引擎另有專屬語法。
  • 生產建構移除註釋,條件註釋已成歷史。

良好的註釋習慣,是代碼可維護性的基石,也是團隊協作的潤滑劑。

copyright © 萬盛學電腦網 all rights reserved