Go os.UserHomeDir 在 CI 没有 HOME 时怎么办

CI 里没有 HOME 时，os.UserHomeDir() 不能被当成“总会返回一个可写目录”的函数。Go 官方文档说明：Unix（含 macOS）读取 $HOME，Windows 读取 %USERPROFILE%，Plan 9 读取 $home；期望变量未设置时，函数可能返回平台默认值，也可能返回非 nil 错误。

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

处理这类 CI 问题的关键不是给空字符串拼接子目录，而是在程序入口检查返回的 error；如果业务确实需要固定工作目录，就由 CI 显式传入一个业务目录，不要把用户主目录当成临时目录的替代品。

先看清 UserHomeDir 依赖哪个变量

UserHomeDir 的名字容易让人误以为它会查询系统账号数据库并始终给出目录。它的公共契约其实是按平台读取约定的环境变量：

这也解释了一个常见误区：在 Linux CI 中删除 HOME，不一定每次都得到同样的空字符串。文档允许平台实现提供默认值，也允许返回错误；应用代码真正可靠的判断点是 err，而不是某一次 runner 的具体路径。

用最小命令复现 HOME 缺失

先不要在完整构建流程里猜测环境。可以把 HOME 从当前进程环境中移除，再运行一个只调用该函数的小程序。命令里的注释说明了每一步的目的：

# 创建一个临时模块，避免把复现步骤混入业务仓库
tmp_dir="$(mktemp -d)"
cd "$tmp_dir"
go mod init example.com/user-home-check

cat > main.go 

这段命令只用于复现 Unix 环境。Windows runner 应使用对应的环境变量清理方式，重点仍然是让测试进程看不到 USERPROFILE 后检查返回的 error。不要把某台机器的输出路径写进断言，因为平台实现和 runner 镜像都可能变化。

入口处统一处理错误，不要拼接空路径

如果应用需要在用户目录下保存配置或缓存，建议把“获取目录”和“创建应用子目录”放在一个小函数里。这样所有调用方都能得到同一种错误语义，也不会出现 filepath.Join("", ".cache") 继续向当前工作目录写文件的情况。

package main

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

func appConfigDir(appName string) (string, error) {
	// UserHomeDir 可能失败；失败时直接返回，不把空字符串当作根目录。
	home, err := os.UserHomeDir()
	if err != nil {
		return "", fmt.Errorf("resolve user home: %w", err)
	}
	if home == "" {
		// 这是防御性检查，避免未来平台实现返回空路径时静默写错位置。
		return "", errors.New("resolve user home: empty path")
	}
	return filepath.Join(home, ".config", appName), nil
}

func main() {
	dir, err := appConfigDir("sample-tool")
	if err != nil {
		// CI 中应让错误进入日志并终止当前任务，而不是继续生成配置文件。
		fmt.Println(err)
		os.Exit(1)
	}
	fmt.Println(dir)
}

这里的 fallback 不是随便猜一个目录。如果产品允许用户通过参数、配置文件或 CI 变量指定目录，可以在调用 appConfigDir 之前完成优先级选择；如果没有明确的业务目录，就应该保留错误，让流水线暴露环境配置缺失。

需要固定落盘位置时，由 CI 显式注入

用户主目录解决的是“当前用户默认位置”，并不等于构建产物目录。构建缓存、测试报告和发布制品更适合使用 CI 提供的工作区变量，或者由任务参数传入绝对路径。示例把业务目录交给环境变量，并保留用户目录作为可选信息：

package main

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

func outputDir() (string, error) {
	if value, ok := os.LookupEnv("APP_OUTPUT_DIR"); ok && value != "" {
		// CI 显式提供的目录优先，避免把制品写入 runner 的用户目录。
		return filepath.Clean(value), nil
	}

	// 没有业务目录时才读取用户主目录，并把失败交给上层处理。
	home, err := os.UserHomeDir()
	if err != nil {
		return "", fmt.Errorf("no APP_OUTPUT_DIR and user home unavailable: %w", err)
	}
	return filepath.Join(home, "sample-tool", "out"), nil
}

func main() {
	dir, err := outputDir()
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	fmt.Println(dir)
}

在实际流水线中，APP_OUTPUT_DIR 的值应由 CI 配置系统生成，而不是把某个开发者电脑上的路径复制进仓库。目录是否存在、是否可写，也应由负责创建文件的那一层按业务需求处理。

测试时注入变量，断言错误而不是断言某个目录

测试的目标是覆盖“变量存在”和“变量缺失”两类输入。由于环境变量是进程级状态，测试中修改它时要用 t.Setenv，让测试结束后自动恢复；同时不要把 Linux、macOS 和 Windows 的默认目录写成同一个期望值。

package homecheck

import (
	"os"
	"testing"
)

func TestUserHomeDirUsesConfiguredHome(t *testing.T) {
	// t.Setenv 会在测试结束后恢复 HOME，避免污染其它测试。
	t.Setenv("HOME", "/ci/home/example")

	dir, err := os.UserHomeDir()
	if err != nil {
		t.Fatalf("UserHomeDir() error = %v", err)
	}
	if dir != "/ci/home/example" {
		t.Fatalf("UserHomeDir() = %q, want configured HOME", dir)
	}
}

func TestBusinessPathDoesNotHideHomeError(t *testing.T) {
	// 业务函数应在没有显式目录时把 UserHomeDir 的失败向上返回。
	t.Setenv("APP_OUTPUT_DIR", "")
	t.Setenv("HOME", "")

	_, err := outputDir()
	if err == nil {
		t.Fatal("outputDir() error = nil, want missing-directory error")
	}
}

第二个测试的细节需要结合目标平台设计：如果当前平台在变量为空时仍提供默认目录，就不应武断地断言 UserHomeDir 一定报错。更稳妥的做法是测试业务函数的契约：没有 APP_OUTPUT_DIR 且用户目录不可用时必须返回错误，并把“不可用”通过依赖注入或独立解析函数表达出来。

升级或迁移时的检查清单

• 调用 os.UserHomeDir 后是否检查了 error？
• 是否把空字符串交给了 filepath.Join、os.Create 或缓存初始化逻辑？
• 构建产物、测试报告和缓存是否有独立的 CI 目录，而不是依赖用户主目录？
• 跨平台测试是否只断言环境变量和错误语义，没有硬编码某个操作系统的默认路径？
• 修改环境变量的测试是否使用了可恢复的测试作用域？

如果只是从本地开发机迁移到 CI，最小修复通常是两步：第一，在读取用户目录的位置处理非 nil error；第二，为需要稳定落盘的业务数据增加显式的 APP_OUTPUT_DIR 或命令行参数。这样即使 runner 没有 HOME，程序也会给出清晰失败原因，而不是在错误目录里生成“看似成功”的文件。

相关问题

os.UserHomeDir 和 os.UserConfigDir 是一回事吗？

不是。前者返回用户主目录，后者返回平台约定的用户配置根目录，并且后者还会考虑 XDG_CONFIG_HOME 等规则。应用要保存配置时，应按数据类型选择 API，并分别处理错误。

HOME 没有设置时能不能直接用当前工作目录？

不建议隐式这样做。当前工作目录由启动方式决定，可能是仓库目录、临时目录或 runner 的工作区。只有当产品明确规定“工作目录就是输出目录”时，才应由参数或 CI 配置显式传入。

为什么本机成功、CI 失败？

本机通常预置了用户目录变量，CI runner 则可能使用最小环境、容器用户或清理后的环境。把环境变量作为输入处理，并为固定产物目录提供显式配置，才能让两者行为一致。