Sass 註解：// 與 /* */ 的差別與壓縮後的行為

Sass 有兩種註解，差別只有一件事：會不會出現在編譯後的 CSS 裡。

寫法	名稱	會輸出到 CSS 嗎
// 說明	單行註解（silent comment）	不會
/* 說明 */	多行註解（loud comment）	會

單行註解

兩條斜線到行尾，只存在於原始碼：

// 主色，改這裡會影響整站按鈕與連結
$brand: #2965f1;

.btn {
  color: $brand; // 行尾也可以
}

.btn {
  color: #2965f1;
}

這是原生 CSS 沒有的寫法，也是絕大多數情況該用的那一種，寫給團隊看的說明沒有理由讓使用者一起下載。

多行註解

與 CSS 相同的寫法，會被輸出：

/* 卡片元件
   由 card.scss 產生 */
.card {
  padding: 16px;
}

/* 卡片元件
   由 card.scss 產生 */
.card {
  padding: 16px;
}

壓縮模式下的行為

用 --style=compressed 編譯時：

註解	結果
// 說明	移除
/* 說明 */	移除
/*! 說明 */	保留

驚嘆號開頭的叫 保留註解，壓縮工具會刻意留著它，用途是授權宣告：

/*! MyUI v2.1.0 | MIT License */

一份專案通常只需要一個保留註解

放在入口檔案最上方標示版本與授權即可。其他說明一律用 //。

註解裡的插值

多行註解會被輸出，所以裡面的 插值 會被計算：

$version: "2.1.0";

/*! MyUI v#{$version} */

/*! MyUI v2.1.0 */

單行註解不會輸出，寫插值沒有意義，Sass 也不會去算它。

註解不能巢狀

這是註解掉大段程式碼時最容易踩的坑：

/*
.card {
  /* 這裡本來就有註解 */
  padding: 16px;
}
*/

第一個 */ 就把外層註解關掉了，後面的 padding: 16px; } */ 變成無效語法，編譯直接失敗。

註解掉整段就用單行註解

編輯器的「切換註解」快捷鍵在 .scss 檔裡預設就是加 //，逐行加上去不會有巢狀問題。

慣例

位置	建議寫法
檔案開頭說明用途	// 區塊
區段分隔	// ---- 按鈕 ----
變數、混入 的用途說明	// 寫在定義上方
授權與版本	/*! */ 放入口檔最上方
暫時停用的程式碼	//，並註明原因與日期

別讓註解變成程式碼的垃圾桶

被註解掉的舊程式碼應該直接刪除，Git 記得住每一版，留在檔案裡只會讓人不敢動它。

常見問題

兩種註解該用哪一種？

預設用兩條斜線的單行註解，它不會出現在產出的 CSS 裡，寫給團隊看的說明都該用它。只有真的需要讓最終使用者看到的內容，例如授權宣告，才用多行註解。

壓縮後註解會不見嗎？

用 --style=compressed 編譯時，一般的多行註解會被移除，只有開頭寫成驚嘆號的保留註解會留下來。單行註解在任何模式下都不會輸出。

註解裡可以放變數嗎？

多行註解裡可以用 插值，寫成 #{$version} 就會在編譯時被換成實際的值，常用於在產出的 CSS 開頭標示版本號。單行註解不會輸出，所以插值在裡面沒有意義。

為什麼註解掉一段 CSS 之後編譯還是報錯？

多行註解不能巢狀，被註解的那段裡若本來就有多行註解，第一個結束符號就會提早關閉註解，後面的內容變成無效語法。註解掉整段程式碼時請改用單行註解。

延伸閱讀

語法構成插值 #{}安裝與編譯除錯 @debug、@warn、@error