golang-spf13-viper

角色設定： 你是一位 Go 工程師，將設定視為分層系統。Flag 優先於 env，env 優先於 file，file 優先於 default——你綁定每個 key，讓所有四層都能透過同一個 API 存取。

在 Go 中使用 spf13/viper 進行分層設定

Viper 從多個來源解析設定值，並遵循固定的優先順序。它沒有使用者介面——不定義指令或 flag。它的工作是回答「現在 key X 的值是什麼？」透過從最高到最低優先順序走訪其來源層。

官方資源：

• pkg.go.dev/github.com/spf13/viper
• github.com/spf13/viper

此技能並非詳盡無遺。請參閱函式庫文件和程式碼範例以獲取更多資訊。Context7 可作為探索平台。如需 Go 套件文件、版本、符號和已知漏洞，→ 請參閱 samber/cc-skills-golang@golang-pkg-go-dev 技能。

go get github.com/spf13/viper@latest

Viper 與 cobra 的比較

Cobra 負責指令樹——子指令、flag、引數驗證、自動補全。Viper 負責設定解析——它透過走訪來源層來回答「key X 的值是什麼？」Viper 沒有使用者介面；它純粹是一個鍵值解析器。僅需 flag 的 CLI 使用 cobra 即可；僅需設定檔的 daemon 使用 viper 即可；兩者都需要時，在 PersistentPreRunE 透過 BindPFlag 綁定 flag。

→ 請參閱 samber/cc-skills-golang@golang-spf13-cobra 技能以了解 cobra 端的整合。

優先順序管線

Viper 按以下順序走訪來源來解析 key（先設定的值優先）：

1. 明確的 Set()      — viper.Set("key", val)    最高優先順序
2. flag                — 綁定的 pflag.Flag
3. 環境變數             — BindEnv / AutomaticEnv
4. 設定檔              — ReadInConfig / MergeInConfig
5. KV 遠端             — etcd / Consul
6. 預設值              — viper.SetDefault("key", val)   最低優先順序

此管線固定且無法重新排序。理解它能防止大多數 viper 錯誤：一個「應該」來自設定檔的 key 可能被環境變數或帶有預設值的 flag 遮蔽。

來源與設定檔

viper.SetConfigName("config")
viper.AddConfigPath("$HOME/.myapp")
if err := viper.ReadInConfig(); err != nil {
    var notFound *viper.ConfigFileNotFoundError
    if !errors.As(err, &notFound) {
        return fmt.Errorf("讀取設定檔: %w", err) // 僅傳播真正的錯誤
    }
}

ConfigFileNotFoundError 必須優雅處理——設定檔通常是可選的。未處理的遺失檔案錯誤會導致僅使用 flag 或環境變數即可正常運行的程式崩潰。

關於支援的格式（JSON、TOML、YAML、HCL、INI、properties）、MergeInConfig 和遠端 KV，請參閱 sources-and-formats.md。

環境變數綁定與 key 替換器

這是 viper 中錯誤密度最高的區域。三個設定必須一起使用——缺少任何一個都會破壞巢狀 key 的解析：

// ✓ 正確——啟動時三者一起設定
viper.SetEnvPrefix("MYAPP")                             // 避免衝突：PORT → MYAPP_PORT
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))  // database.host → MYAPP_DATABASE_HOST
viper.AutomaticEnv()

// ✗ 錯誤——沒有 SetEnvKeyReplacer，viper 會尋找 MYAPP_DATABASE.HOST（保留點號）

關於 BindEnv、AllowEmptyEnv 和 env 與 default 的互動，請參閱 binding-and-env.md。

Flag 綁定（cobra 的接合點）

在 init() 或 PersistentPreRunE 中將 cobra flag 綁定到 viper——絕不要在 RunE 中（設定載入已在 PersistentPreRunE 中執行，因此在 RunE 中設定的綁定會被錯過）：

func init() {
    rootCmd.PersistentFlags().Int("port", 8080, "監聽埠號")
    viper.BindPFlag("port", rootCmd.PersistentFlags().Lookup("port"))
    // viper.BindPFlags(cmd.Flags()) — 一次綁定整個 FlagSet
}

關於 AllowEmptyEnv 和 flag/env 互動細節，請參閱 binding-and-env.md。

解組到結構體

viper.Unmarshal 使用 mapstructure 將解析後的設定映射到結構體：

type Config struct {
    Port     int `mapstructure:"port"`
    Database struct {
        MaxConn int `mapstructure:"max_conn"` // 明確標籤：mapstructure 不會將底線轉換為駝峰
    } `mapstructure:"database"`
}
var cfg Config
viper.Unmarshal(&cfg)

務必使用 mapstructure 標籤——隱式映射對於巢狀結構體和底線命名字段來說很脆弱。優先使用 UnmarshalKey("database", &dbCfg) 而非 Sub("database").Unmarshal——它避免了 Sub 在 key 不存在時需要 nil 檢查。

關於 time.Duration / net.IP / slice 解碼器和自訂 DecodeHook 註冊，請參閱 unmarshal.md。

子樹

viper.Sub("database") 回傳一個作用域為該前綴的新 *viper.Viper，如果 key 不存在則回傳 nil——在對結果呼叫方法前務必檢查 nil。優先使用 UnmarshalKey("database", &dbCfg)，它完全避免了 nil 風險。

熱重載

viper.WatchConfig()
viper.OnConfigChange(func(e fsnotify.Event) { /* 重新套用變更的值 */ })

WatchConfig 使用 fsnotify 並監控 inode。透過重新命名進行原子寫入的編輯器（vim、neovim）會取代 inode——回呼可能不會觸發。使用 echo >> config.yaml 測試熱重載，而非編輯器儲存。關於執行緒安全的重載模式，請參閱 watch-and-reload.md。

測試隔離

絕不要在測試中使用全域 viper——狀態會跨測試案例洩漏。每個測試使用 viper.New()，讓每個實例隔離：

v := viper.New()
v.SetConfigFile("testdata/config.yaml")
require.NoError(t, v.ReadInConfig())

關於 t.Setenv 互動和 Reset() 限制，請參閱 testing-and-isolation.md。

最佳實踐

1. 同時設定前綴、key 替換器和 AutomaticEnv——缺少任何一個會導致巢狀環境變數 key 靜默無法解析（database.host → DATABASE.HOST 而非 DATABASE_HOST）。
2. 優雅處理 ConfigFileNotFoundError——遺失設定檔不應導致僅使用 flag 和環境變數執行的服務崩潰。
3. 務必在設定結構體上使用 mapstructure 標籤——隱式映射會靜默遺漏巢狀和底線命名字段。
4. 在測試中使用 viper.New()，絕不使用全域——全域會跨測試執行累積狀態；每個測試的實例是隔離的。
5. 在 Execute() 之前綁定 flag——在 RunE 中綁定太晚；cobra 在 RunE 執行前已解析 flag。

常見錯誤

錯誤	失敗原因	修正
AutomaticEnv 沒有 SetEnvKeyReplacer	database.host 尋找 MYAPP_DATABASE.HOST（保留點號）——永遠不匹配	在 AutomaticEnv 前加上 SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
結構體欄位沒有 mapstructure 標籤	靜默遺漏巢狀和底線命名字段	為每個欄位加上 mapstructure:"key_name"
在測試中使用全域 viper	一個測試的狀態污染下一個測試，導致不穩定的順序	每個測試建立 viper.New()
缺少 ConfigFileNotFoundError 檢查	遺失設定檔會導致應僅依賴 flag/env 執行的服務崩潰	errors.As(err, &notFound)——僅傳播非 not-found 的錯誤

延伸閱讀

• sources-and-formats.md — 支援的檔案格式、多路徑搜尋、MergeInConfig、遠端 KV（etcd/Consul）
• binding-and-env.md — BindEnv、AutomaticEnv、SetEnvPrefix、SetEnvKeyReplacer、AllowEmptyEnv、時機規則
• unmarshal.md — Unmarshal、UnmarshalKey、mapstructure 標籤、自訂 DecodeHooks（Duration、IP、slice）
• watch-and-reload.md — WatchConfig、OnConfigChange、fsnotify 注意事項、原子重新命名陷阱、執行緒安全模式
• testing-and-isolation.md — 每個測試使用 viper.New()、t.Setenv 互動、Reset() 限制、快照/還原

交叉參考

• → 請參閱 samber/cc-skills-golang@golang-cli 技能以了解一般 CLI 架構——專案佈局、退出碼、訊號處理、cobra+viper 整合
• → 請參閱 samber/cc-skills-golang@golang-spf13-cobra 技能以了解 cobra 端的整合（flag 定義與綁定）
• → 請參閱 samber/cc-skills-golang@golang-testing 技能以了解一般 Go 測試模式

如果你遇到 spf13/viper 的錯誤或非預期行為，請在 https://github.com/spf13/viper/issues 開啟 issue。