Go os.UserCacheDir 怎样选择跨平台缓存目录

跨平台 Go 程序不要手写 ~/.cache、AppData 或 macOS 的固定路径。更稳妥的入口是 os.UserCacheDir()：它返回当前用户的缓存根目录，应用再在里面创建自己的子目录。缓存可以被删除或重建，所以不要把唯一的用户配置和业务数据放在这里。

官方地址：https://pkg.go.dev/os#UserCacheDir

先分清缓存目录要解决什么问题

缓存适合放编译产物、缩略图、索引或可以重新下载的数据。它和配置目录、临时目录不是一回事：用户设置通常应考虑 os.UserConfigDir()，短生命周期的临时文件则看 os.TempDir()。把三者混用，会导致清理缓存时误删设置，或让临时文件长期占用用户空间。

UserCacheDir 的返回值是“根目录”，不是某个应用已经准备好的完整目录。官方文档建议程序在其下创建应用专属子目录，并自行决定文件名和缓存格式。

不同系统如何决定缓存根目录

函数会按当前目标系统的约定返回路径。Unix 使用非空的 XDG_CACHE_HOME；如果它没有设置，则使用 $HOME/.cache。macOS 返回 $HOME/Library/Caches，Windows 返回 %LocalAppData%，Plan 9 返回 $home/lib/cache。这些平台根目录的差异正是应该交给标准库处理的部分。

有两个容易忽略的错误边界：如果无法确定用户位置，例如 $HOME 不存在，函数会返回错误；如果 Unix 上的 XDG_CACHE_HOME 是相对路径，也会返回错误。不要在收到错误后盲目把当前工作目录当成缓存目录，这会让程序把数据写进不可预期的位置。

在根目录下创建应用自己的缓存目录

应用名应是稳定、受控的单个目录名，例如 demo-index，而不是直接把用户输入当成路径。下面的函数先获取根目录，再拼接应用子目录，最后创建目录；每个失败点都保留原始错误，便于调用方决定降级或退出。

package cache

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

// Dir 返回应用专属缓存目录；app 应由程序固定配置，而不是任意用户输入。
func Dir(app string) (string, error) {
	root, err := os.UserCacheDir()
	if err != nil {
		return "", fmt.Errorf("find user cache root: %w", err) // 根目录不可确定时交给上层降级。
	}
	if app == "" || app == "." || app == ".." || filepath.Base(app) != app {
		return "", fmt.Errorf("invalid cache app name: %q", app) // 防止应用名改变目录层级。
	}
	dir := filepath.Join(root, app)
	if err := os.MkdirAll(dir, 0o700); err != nil {
		return "", fmt.Errorf("create cache directory: %w", err) // 目录权限或磁盘问题不能被吞掉。
	}
	return dir, nil
}

filepath.Join 会使用目标平台的路径分隔符，MkdirAll 允许目录已经存在。这里使用较保守的 0700，适合缓存中可能包含用户相关数据的程序；如果缓存本来就允许同一台机器上的其他用户读取，再根据产品的权限模型调整。

写入缓存时要保留哪些错误语义

获取目录成功不等于后续写入一定成功。磁盘只读、权限不足、配额耗尽或目录被外部删除，都可能在 os.WriteFile 时出现。缓存不是业务事实的唯一来源，因此写入失败通常应该记录并继续使用主流程，而不是把可重建数据当成致命数据。

func Save(dir, name string, data []byte) error {
	path := filepath.Join(dir, name)
	if err := os.WriteFile(path, data, 0o600); err != nil {
		return fmt.Errorf("write cache %q: %w", name, err) // 调用方可记录后继续主流程。
	}
	return nil
}

func Load(dir, name string) ([]byte, error) {
	data, err := os.ReadFile(filepath.Join(dir, name))
	if err != nil {
		return nil, fmt.Errorf("read cache %q: %w", name, err) // 不存在时由上层重新计算或下载。
	}
	return data, nil
}

如果缓存目录根本无法确定，可以禁用缓存并继续业务；如果目录能确定但创建失败，则记录平台、错误和应用名，避免在日志中打印可能包含隐私的完整路径。对重要缓存文件还可以先写临时文件再替换，但那属于文件一致性设计，不能由 UserCacheDir 自动保证。

相关问题

UserCacheDir 会自动创建目录吗？

不会。它只返回适合当前用户的缓存根目录，应用专属子目录需要自行用 MkdirAll 创建。

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

因为不同系统的缓存约定不只是“用户主目录加一个固定后缀”，Unix 还受到 XDG 变量影响。直接拼接会绕过这些约定。

XDG_CACHE_HOME 设置成相对路径可以吗？

不可以。相对路径无法稳定表达用户缓存根目录，UserCacheDir 会返回错误，调用方应修正环境或关闭缓存。