Go os.UserConfigDir 怎么选择跨平台用户配置目录

Go 程序需要保存当前用户的配置时，不要直接拼接 $HOME/.config，也不要把 macOS 的目录规则硬编码进业务代码。更稳妥的入口是 os.UserConfigDir()：它返回“用户配置根目录”，应用再在里面创建自己的子目录。

先分清 UserConfigDir 返回的是什么

os.UserConfigDir 返回的是当前用户配置数据的默认根目录，不是某个应用的最终文件名。官方约定是：Unix 优先使用非空的 XDG_CONFIG_HOME，否则使用 $HOME/.config；macOS 使用 $HOME/Library/Application Support；Windows 使用 %AppData%；Plan 9 使用 $home/lib。

这几个平台规则的共同点是“根目录由系统约定决定，应用目录由程序负责命名”。因此调用成功后还应追加一个稳定的应用名，例如 example-tool，避免把配置文件直接散落在公共根目录。

最小配方：先处理错误，再拼接路径

这个 API 返回 (string, error)，错误不能被忽略。比如 Unix 的 XDG_CONFIG_HOME 是相对路径，或者系统无法确定用户主目录时，函数就可能失败。把空字符串继续交给 filepath.Join，会让问题变成一个难定位的相对路径。

package main

import (
    "fmt"
    "os"
    "path/filepath"
)

func configFile() (string, error) {
    root, err := os.UserConfigDir()
    if err != nil {
        // 配置根目录无法确定时，交给上层决定降级或退出。
        return "", fmt.Errorf("find user config directory: %w", err)
    }

    // Join 会使用当前平台的分隔符，不要手写斜杠拼路径。
    return filepath.Join(root, "example-tool", "config.json"), nil
}

func main() {
    path, err := configFile()
    if err != nil {
        // 这里保留原始错误，便于区分环境变量和权限问题。
        fmt.Println(err)
        return
    }
    fmt.Println(path)
}

这里的关键不是把路径打印出来，而是把“定位失败”和“文件读写失败”分成两个阶段。这样调用方可以在找不到配置根目录时明确提示，而不会误以为配置文件只是不存在。

创建目录和保存文件时，权限要分开

UserConfigDir 不会创建返回的目录。保存配置前，可以创建应用子目录；目录通常使用 0700，文件使用 0600，这样默认只允许当前用户访问。实际权限还会受到操作系统和 umask 影响，写入后仍应把错误返回给调用方。

func saveConfig(data []byte) error {
    path, err := configFile()
    if err != nil {
        return err
    }

    // 只创建应用自己的目录，避免改动整个用户配置根目录的权限。
    if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
        return fmt.Errorf("create config directory: %w", err)
    }

    // 0600 表示新建文件默认只允许当前用户读写。
    if err := os.WriteFile(path, data, 0600); err != nil {
        return fmt.Errorf("write config file: %w", err)
    }
    return nil
}

读取时可以把“不存在”当作首次启动，把其他错误继续上报；保存时则不能吞掉磁盘满、只读目录或权限不足等错误。配置内容若涉及密钥，还应在应用层考虑原子替换和更严格的密钥管理，这不属于目录选择本身。

常见问题

为什么不直接使用 os.UserHomeDir？

UserHomeDir 只告诉你用户主目录，不能替代不同平台的配置目录约定。只有当业务明确需要主目录本身时才使用它；保存应用配置优先选择 UserConfigDir。

UserConfigDir 会自动创建 example-tool 目录吗？

不会。它只返回根路径。应用目录和配置文件要按需创建，并分别处理 MkdirAll 与 WriteFile 的错误。

XDG_CONFIG_HOME 设置成相对路径会怎样？

函数会返回错误，而不是替你把相对路径转换成绝对路径。调用方应提示用户修正环境变量，或采用明确记录过的降级策略，不能静默写入当前工作目录。

把平台规则交给 os.UserConfigDir，把应用命名交给 filepath.Join，再把目录权限、文件权限和错误处理拆开，Go 配置文件路径就能从“某台机器能用”变成可迁移的实现。