HTML 本身只有單一種註解語法,但實務上常在模板檔中混寫 CSS、JavaScript、伺服器端語言。本文釐清 HTML 多行註解正確寫法,並提供主流語言註解語法對照表,方便全端開發快速查閱。
HTML 多行註解:正確寫法
<!--
這是多行註解
可以跨越任意行數
適合:區塊說明、暫時停用大段代碼、版權聲明
-->
關鍵規則提醒
- 起始 `
<!--`、結束 `-->` 固定格式
- 內容不可包含 `
--` 序列(會提前結束)
- 不支援巢狀:外層註解會在第一個內層結束標記處關閉
- 若需巢狀效果,改用區塊標記法:
<!-- 外層區塊 START -->
<!-- 內層區塊 START -->
內容
<!-- 內層區塊 END -->
<!-- 外層區塊 END -->
主流語言註解語法對照表
| 語言/環境 | 單行註解 | 多行註解 | 特殊/文檔註解 | 適用檔案/位置 |
| HTML | <!-- 註解 --> | - | .html, .htm, 模板檔 |
| CSS | /* 註解 */ | - | .css, <style> |
| JavaScript | // 註解 | /* 註解 */ | /** JSDoc */ | .js, <script> |
| TypeScript | // 註解 | /* 註解 */ | /** TSDoc */ | .ts, .tsx |
| JSX/TSX | {/* 註解 */} | {/* 多行 */} | - | React 元件內部 |
| Vue SFC | <!-- --> (template) | <!-- --> (template) | - | .vue <template> |
| // / /* */ (script) | /* */ (script) | /** */ | .vue <script> |
| PHP | // 或 # | /* */ | /** PHPDoc */ | .php, <?php ?> |
| Python | # 註解 | """ 多行字串 """ | """ Docstring """ | .py |
| Java / C# / C++ | // | /* */ | /** Javadoc */ / /// XML Doc | .java, .cs, .cpp |
| Go / Rust | // | /* */ | /// Doc comment | .go, .rs |
| SQL | -- 註解 | /* */ | - | .sql |
| Shell / Bash | # 註解 | - | - | .sh |
| YAML | # 註解 | - | - | .yaml, .yml |
| JSON | ❌ 不支援註解 | - | .json (用 JSONC 或移除註解) |
| Markdown | <!-- 註解 --> (HTML 註解) | - | .md (不會輸出到 HTML) |
| Dockerfile | # 註解 | - | - | Dockerfile |
| Nginx/Apache Conf | # 註解 | - | - | .conf |
模板引擎專屬註解(編譯後不輸出到 HTML,更安全)
| 引擎 | 語法 | 特點 |
| Blade (Laravel) | {{-- 註解 --}} | 僅存在伺服器端,不輸出到瀏覽器 |
| Twig (Symfony) | {# 註解 #} | 支援多行,不輸出 |
| Jinja2 (Flask/Django) | {# 註解 #} | 支援多行,不輸出 |
| Nunjucks | {# 註解 #} | 支援多行,不輸出 |
| EJS | <%-- 註解 --%> | 不輸出 |
| Handlebars | {{! 註解 }} | 單行,不輸出 |
| Mustache | {{! 註解 }} | 單行,不輸出 |
VS Code / IDE 快捷鍵
| 編輯器 | 切換行註解 | 切換區塊註解 |
| VS Code | Ctrl/Cmd + / | Shift+Alt+A (HTML/CSS/JS) |
| WebStorm/PhpStorm | Ctrl/Cmd + / | Ctrl/Cmd + Shift + / |
| Sublime Text | Ctrl/Cmd + / | Ctrl/Cmd + Shift + / |
| Vim/Neovim | gcc (需插件 commentary.vim) | gc (視覺模式選取後) |
最佳實踐建議
- HTML 檔案中: 僅使用 `
<!-- -->`;`<style>` 內用 CSS 註解;`<script>` 內用 JS 註解。
- 模板檔: 優先使用模板引擎專屬註解(不輸出到前端),敏感邏輯/備註專用。
- 生產建構: 配置移除 HTML/CSS/JS 註解(保留版權聲明),減少體積與資訊洩露。
- 團隊規範: 統一 TODO/FIXME/NOTE 格式,如 `
<!-- TODO(@name): 說明 -->`,配合工具掃描。
熟記各語言註解語法差異,能在全端開發、Code Review、跨語言專案中避免語法錯誤,也能善用模板引擎專屬註解保護伺服器端邏輯不外洩。