How to Use Vim Modeline to Force Filetype and Formatting

在使用 Vim / Neovim 編輯設定檔（例如 nginx、Docker、env、conf）時，常常會遇到：

• 副檔名看不出類型
• 語法高亮錯誤
• 縮排混亂
• LSP / 補全失效

這時候可以使用一個超好用但很多人沒用過的功能：

👉 Vim Modeline

🔹 什麼是 Vim Modeline？

Modeline 是一種寫在檔案開頭或結尾的註解，用來告訴 Vim「這個檔案要用什麼設定」。

Vim 開啟檔案時會自動讀取並套用。

最常見用途：

• 指定語法類型（filetype）
• 設定 tab 寬度
• 控制縮排風格
• 強制編碼

---

🔹 基本語法

# vim: set ft=nginx :

結構說明：

區段	說明
#	註解符號
vim:	宣告這是 Modeline
set	設定
ft=nginx	指定 filetype
:	結尾標記

等同於在 Vim 內手動輸入：

:set ft=nginx

✅ 精簡寫法

下面這三種「效果完全一樣」：

# vim: set ft=nginx :
# vim: ft=nginx :
# vim:ft=nginx

優點：

• ✅ 超短
• ✅ 不佔版面
• ✅ 非常適合放在第一行
• ✅ 設定檔實務最常用

---

✅ 精簡寫法也可以組合多個設定

# vim:ft=nginx ts=2 sw=2

# vim:ft=sh ts=2 sw=2 expandtab

# vim:ft=python ts=4 sw=4 expandtab

全部都是 ✅ 合法 Modeline。

---

✅ 最常用 Modeline 範例整理

✅ 強制指定語法類型（最常見用途）

# vim: set ft=nginx :
# vim: set ft=sh :
# vim: set ft=php :
# vim: set ft=python :
# vim: set ft=javascript :
# vim: set ft=typescript :
# vim: set ft=go :
# vim: set ft=lua :
# vim: set ft=json :
# vim: set ft=yaml :
# vim: set ft=dockerfile :

---

✅ 指定 Tab 與縮排格式

# vim: set ts=2 sw=2 :
# vim: set ts=4 sw=4 :
# vim: set expandtab :
# vim: set noexpandtab :

設定	功能
ts	Tab 顯示寬度
sw	自動縮排寬度
expandtab	Tab 轉為空白
noexpandtab	保留真實 Tab

---

✅ 組合技（實務最常用）

Nginx 設定檔

# vim: set ft=nginx ts=2 sw=2 :

Shell Script

# vim: set ft=sh ts=2 sw=2 expandtab :

Python

# vim: set ft=python ts=4 sw=4 expandtab :

Frontend 專案

// vim: set ft=javascript ts=2 sw=2 :

---

✅ 指定檔案編碼

# vim: set fileencoding=utf-8 :

---

✅ 放在檔案結尾的寫法（也合法）

# vim: set ft=nginx :

---

🔐 Modeline 安全性補充

某些 Vim 會預設關閉 Modeline，避免被惡意檔案注入指令。

你可以檢查：

:set modeline?

啟用方式：

:set modeline

永久啟用（vimrc / init.lua）：

set modeline

---

✅ 什麼時候「一定要用」Modeline？

• 副檔名錯誤的設定檔（.conf、.env、.tpl）
• 後端 mix 多種語言
• Docker / K8s / Nginx / CI 設定
• 團隊統一格式規範