os/exec Cmd.Dir 固定子进程工作目录的配置

外部命令明明能启动，却在运行时找不到相对配置文件、输入目录或输出位置，最常见的原因不是命令参数写错，而是子进程继承了一个并不适合它的工作目录。Go 的 os/exec 用 Cmd.Dir 固定子进程工作目录后，命令内部的相对路径就有了稳定的锚点。

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

需要让外部命令在 /srv/report-job 下读取 config/app.yaml，就把 cmd.Dir 设为这个目录；不要先修改 Go 父进程的当前目录。Dir 为空时，子进程才会使用调用进程的当前目录。

相对路径到底由谁解释

排查这类问题时，我会先把路径分成四类：Go 父进程的当前目录、Cmd.Dir、Cmd.Path 指向的可执行文件，以及命令参数里由外部程序自己解析的资源路径。它们经常被写在同一段代码里，但职责并不相同。

• Dir 为空：子进程使用调用者的当前目录。
• Dir 非空：子进程以它作为工作目录，命令内部的相对配置和输出路径以此为基准。
• Path 使用相对路径：官方文档说明它会相对于 Dir 评价，而不是简单地相对于调用者目录。
• Command("tool") 没有路径分隔符时会通过 LookPath 查找程序；这和参数中的 config/app.yaml 是两套路径问题。

因此，看到“本机能读到，服务里读不到”时，第一项证据应该是子进程的工作目录，而不是立刻给所有文件路径加上绝对路径。把工作目录固定下来，通常能让同一条命令在任务调度器、HTTP 服务和本地命令行中保持一致。

用 Cmd.Dir 固定子进程工作目录

下面的例子让一个 Unix 命令在固定目录中读取相对文件。示例使用 sh 只是为了展示外部程序如何消费相对路径；如果实际调用的是业务工具，应直接把工具名和参数分别传给 exec.Command，不要把整条命令拼成字符串。

package main

import (
	"fmt"
	"os/exec"
)

func runReport() error {
	// Dir 只影响新建的子进程，不会改变当前 Go 进程的工作目录。
	cmd := exec.Command("sh", "-c", "pwd && cat config/app.yaml")
	cmd.Dir = "/srv/report-job"

	output, err := cmd.CombinedOutput()
	if err != nil {
		// 保留命令输出，便于区分目录错误和外部程序自己的退出错误。
		return fmt.Errorf("report command failed: %w; output=%s", err, output)
	}
	fmt.Printf("report command output: %s", output)
	return nil
}

这里的 cat config/app.yaml 并没有改成 /srv/report-job/config/app.yaml，但它的解析基准已经由 cmd.Dir 固定。更重要的是，设置 Dir 不会让父进程后续的文件操作自动切换到该目录；Go 代码中的 os.ReadFile("config/app.yaml") 仍然使用父进程自己的当前目录。

目录不存在时，先看启动阶段的错误

Cmd.Dir 指向不存在的目录、普通文件或当前用户无法进入的目录时，问题发生在子进程真正执行前。此时不要把它和外部命令返回的非零退出码混为一谈，错误文本中的路径通常就是最直接的定位线索。

package main

import (
	"errors"
	"fmt"
	"os"
	"os/exec"
)

func runWithDirectory(workdir string) error {
	// 先保存目录配置，错误中带上业务上下文，方便定位哪个任务传错了路径。
	cmd := exec.Command("report-tool", "--input", "config/app.yaml")
	cmd.Dir = workdir

	if err := cmd.Run(); err != nil {
		var pathErr *os.PathError
		if errors.As(err, &pathErr) {
			// PathError 通常指向启动文件或目录阶段，而不是工具业务失败。
			return fmt.Errorf("cannot start report-tool in %q: %w", workdir, pathErr)
		}
		// 非零退出码仍然保留原始错误，交给上层决定是否重试。
		return fmt.Errorf("report-tool exited in %q: %w", workdir, err)
	}
	return nil
}

如果命令可以启动但读取 config/app.yaml 失败，错误可能来自工具自身，不能仅凭 Cmd.Dir 就断定目录配置一定错误。此时要继续核对：目录里是否真的有该文件、工具是否期待另一个参数名，以及工具是否在内部再次改变了目录。

相对可执行文件也会受到 Dir 影响

一个容易漏掉的边界是：Cmd.Path 本身也可能是相对路径。官方 Cmd 文档说明，Path 为相对路径时，会相对于 Dir 评价。因此下面的 ./bin/report-tool 表示工作目录下的 bin/report-tool，而不是 Go 父进程目录下的同名文件。

package main

import (
	"fmt"
	"os/exec"
)

func runLocalTool() error {
	// Path 是相对路径时，Dir 是它的解析基准：/srv/report-job/bin/report-tool。
	cmd := exec.Command("./bin/report-tool", "--input", "config/app.yaml")
	cmd.Dir = "/srv/report-job"

	if err := cmd.Run(); err != nil {
		// 把 Dir 和 Path 一起记录，避免只看到“文件不存在”却找错目录。
		return fmt.Errorf("run %s from %s: %w", cmd.Path, cmd.Dir, err)
	}
	fmt.Println("report tool finished")
	return nil
}

如果程序由部署系统安装到固定绝对路径，通常优先使用绝对可执行文件路径，再单独设置 Dir。如果确实需要随工作目录携带工具，就要把工具文件、配置文件和权限作为同一个目录契约管理。

Env 与 Unix 下的 PWD 不要混淆

默认情况下，cmd.Env 为 nil，子进程继承当前进程环境。Go 官方文档还说明，在 Unix 系统上，Dir 会影响子进程的 PWD 环境变量，前提是调用方没有另外指定它。手动重建环境时，最稳妥的做法是从 os.Environ() 开始追加业务变量，而不是凭空只保留几项。

package main

import (
	"os"
	"os/exec"
)

func commandWithEnvironment() *exec.Cmd {
	cmd := exec.Command("report-tool", "--input", "config/app.yaml")
	cmd.Dir = "/srv/report-job"

	// 继承 PATH、HOME 等基础环境，再覆盖本任务需要的变量。
	cmd.Env = append(os.Environ(), "REPORT_MODE=scheduled")
	return cmd
}

若业务工具明确要求自定义 PWD，应把它当作工具协议的一部分单独确认；不要因为打印出的环境变量看起来正确，就忽略真实工作目录与符号链接路径之间的差异。

用证据反向确认配置生效

最后一轮排查不要只看 Go 代码中的赋值语句，要让子进程给出它自己的工作目录，并同时记录命令路径、目录配置和原始错误。这样能快速回答三个问题：子进程在哪个目录、相对可执行文件以哪里为基准、失败发生在启动还是业务执行阶段。

package main

import (
	"fmt"
	"os/exec"
)

func inspectWorkdir(workdir string) error {
	// pwd 的输出来自子进程本身，可用于确认 Dir 是否传到了子进程。
	cmd := exec.Command("pwd")
	cmd.Dir = workdir

	output, err := cmd.Output()
	if err != nil {
		// Output 返回的错误保留原始类型，方便上层继续 errors.As。
		return fmt.Errorf("inspect child cwd %q: %w", workdir, err)
	}
	fmt.Printf("child cwd=%s", output)
	return nil
}

在真实任务中，可以把 workdir、cmd.Path、参数摘要和错误类型写入结构化日志，但不要把包含密钥的完整环境变量或敏感参数直接记录。路径证据足够时，排查会比“给路径多加几个 ../”可靠得多。

一份可直接复用的检查清单

1. 确认问题是子进程的相对路径，而不是 Go 父进程自己的文件操作。
2. 为命令设置明确的 cmd.Dir，不要通过修改全局当前目录来补救。
3. 检查 Cmd.Path 是否为相对路径，并确认它与 Dir 的组合确实指向目标文件。
4. 目录不存在或无法进入时，优先识别 os.PathError；命令启动后再分析退出码。
5. 需要自定义环境时，从 os.Environ() 继承基础环境，谨慎覆盖 PWD。
6. 让子进程输出自身工作目录，保留原始错误和必要的路径上下文。

相关问题：如果只想让某一次文件读取使用另一个目录，应直接拼出经过校验的绝对路径；如果整个外部工具都围绕项目目录工作，使用 Cmd.Dir 更能保持参数简洁和行为稳定。两者不要混成“修改 Go 进程当前目录”这一种做法。