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 設定
• 團隊統一格式規範

Using AI Turn My Requirement Into A Spec

LLM 最強大的就是你給予適當的內容，它可以幫你延伸很多你沒注意到的問題，最近常常把需求稍微梳理過後，加上一段 prompt 讓他整理成 spec，再將結果調整一下變可以開 redmine 的票。

widget 設定完成後，若使用者將 widget 的欄位刪除，有機率會造成計算或使用錯誤，經討論後端要先行驗證欄位是否存在，查找有問題後一律回覆 422 給前端

---

你的角色是網路工程師。請協助將我提供的功能簡述，轉換成規格（spec）格式。轉換後的 spec 需包含以下幾個內容：

- 功能標題
- 功能簡述
- 實作建議
- 測試建議
- 其他注意事項

允許使用 emoji 輔助

# 📌 Widget 欄位存在性驗證（後端）

## 📝 功能簡述

當使用者完成 widget 設定後，如果後續手動刪除了 widget 所需的欄位，可能導致運算錯誤或使用體驗異常。後端需在每次相關操作前進行欄位存在性驗證，若必填欄位不存在，統一回傳 HTTP 422 錯誤給前端。

---

## 🛠️ 實作建議

1. **欄位驗證邏輯**

   * 在 widget 運算、讀取前加入一段欄位檢查邏輯。
   * 驗證所有 widget 設定中宣告的欄位是否存在於資料來源（如資料庫欄位、配置檔或動態欄位列表）。
   * 若任一欄位不存在，立即中止流程並回傳 422。

2. **統一錯誤格式**

   * 使用統一格式，例如：
        ```json
        {
          "message": "missing field",
          "code": "CO-ME108",
          "status": false
        }
        ```
        **此 message 以及 code 為示意。**

---

## 🧪 測試建議

1. **正常情境**
   * 所有欄位都存在 → 回傳 200 並正常執行邏輯。

2. **單一欄位缺失**
   * 刪除一個 widget 必要欄位 → 應回傳 422，且錯誤訊息不包含該欄位名稱。

3. **多個欄位缺失**
   * 模擬多個欄位被刪除 → 應回傳 422，且錯誤訊息不包含該欄位名稱。

其實他寫了相當多建議，這是我整理過後的結果，那些建議不一定符合我們需求，但可以當作參考也是相當不錯。

Using AI Turn My Requirement Into A Spec

LLM 最強大的就是你給予適當的內容，它可以幫你延伸很多你沒注意到的問題，最近常常把需求稍微梳理過後，加上一段 prompt 讓他整理成 spec，再將結果調整一下變可以開 redmine 的票。

widget 設定完成後，若使用者將 widget 的欄位刪除，有機率會造成計算或使用錯誤，經討論後端要先行驗證欄位是否存在，查找有問題後一律回覆 422 給前端

---

你的角色是網路工程師。請協助將我提供的功能簡述，轉換成規格（spec）格式。轉換後的 spec 需包含以下幾個內容：

- 功能標題
- 功能簡述
- 實作建議
- 測試建議
- 其他注意事項

允許使用 emoji 輔助

# 📌 Widget 欄位存在性驗證（後端）

## 📝 功能簡述

當使用者完成 widget 設定後，如果後續手動刪除了 widget 所需的欄位，可能導致運算錯誤或使用體驗異常。後端需在每次相關操作前進行欄位存在性驗證，若必填欄位不存在，統一回傳 HTTP 422 錯誤給前端。

---

## 🛠️ 實作建議

1. **欄位驗證邏輯**

   * 在 widget 運算、讀取前加入一段欄位檢查邏輯。
   * 驗證所有 widget 設定中宣告的欄位是否存在於資料來源（如資料庫欄位、配置檔或動態欄位列表）。
   * 若任一欄位不存在，立即中止流程並回傳 422。

2. **統一錯誤格式**

   * 使用統一格式，例如：
        ```json
        {
          "message": "missing field",
          "code": "CO-ME108",
          "status": false
        }
        ```
        **此 message 以及 code 為示意。**

---

## 🧪 測試建議

1. **正常情境**
   * 所有欄位都存在 → 回傳 200 並正常執行邏輯。

2. **單一欄位缺失**
   * 刪除一個 widget 必要欄位 → 應回傳 422，且錯誤訊息不包含該欄位名稱。

3. **多個欄位缺失**
   * 模擬多個欄位被刪除 → 應回傳 422，且錯誤訊息不包含該欄位名稱。

其實他寫了相當多建議，這是我整理過後的結果，那些建議不一定符合我們需求，但可以當作參考也是相當不錯。