Go os.Root 路径打开怎样限制在根目录内处理空输入并保留错误边界

如果文件名来自请求参数、压缩包条目或插件配置，直接把它和固定目录用 `filepath.Join` 拼起来并不能形成可靠的目录边界。Go 1.24 引入的 `os.Root` 可以把打开动作绑定到一个根目录内；这篇用一个小型读取函数处理三个容易混淆的输入：空字符串、`.` 和越界路径。

官方资料：https://pkg.go.dev/os

空输入应该在业务层先拒绝；真正打开文件时使用 root.Open(name)，让 os.Root 处理父目录、绝对路径和符号链接越界，并用 %w 保留原始错误。

先把空字符串和点路径分开

os.Root 的方法接收相对于根目录的名称。. 表示根目录本身，因此可以用于读取目录元信息；空字符串不是同一个意思，内部路径拆分会返回空路径错误。把空字符串默认为 .，会让“调用方没有提供文件名”和“调用方明确请求根目录”混在一起。

用 os.Root 写一个只读小工具

示例函数只负责“在根目录内读取一个文件”。它不把外部输入拼成宿主机绝对路径，也不为了方便而调用 filepath.Clean 后再用前缀比较。前缀比较会遇到同名目录、符号链接和平台路径规则等边界，根目录 API 才是这里的约束主体。

package rootread

import (
    "errors"
    "fmt"
    "io"
    "os"
)

// ErrEmptyName 表示调用方没有提供相对文件名。
var ErrEmptyName = errors.New("empty relative name")

// ReadWithinRoot 只读取 rootDir 下的 name，并保留可判断的错误链。
func ReadWithinRoot(rootDir, name string) (data []byte, err error) {
    if name == "" {
        // 空字符串是输入契约错误，不把它伪装成根目录 "."。
        return nil, fmt.Errorf("read within root: %w", ErrEmptyName)
    }

    root, err := os.OpenRoot(rootDir)
    if err != nil {
        // %w 保留打开根目录时的 *os.PathError。
        return nil, fmt.Errorf("open root %q: %w", rootDir, err)
    }
    defer func() {
        // 读操作已经成功但关闭失败时，仍把关闭错误交给调用方。
        if closeErr := root.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("close root: %w", closeErr)
        }
    }()

    file, err := root.Open(name)
    if err != nil {
        // 越界、绝对路径或不存在的文件都从这里返回原始路径错误。
        return nil, fmt.Errorf("open %q: %w", name, err)
    }
    defer func() {
        // 文件关闭错误不能覆盖前面已经发生的读取错误。
        if closeErr := file.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("close file: %w", closeErr)
        }
    }()

    data, err = io.ReadAll(file)
    if err != nil {
        return nil, fmt.Errorf("read %q: %w", name, err)
    }
    return data, nil
}

这里有两个细节值得保留。第一，name == "" 只判断真正的空字符串，不随意裁剪空格，因为空格可能是文件名的一部分。第二，两个 defer 使用命名返回值，把关闭失败纳入错误链，同时避免关闭错误覆盖已经发生的读取错误。

调用方怎样识别不同错误

错误字符串适合日志，不适合业务分支。空输入是我们定义的业务边界，可以用 errors.Is；根目录不存在、路径越界和文件不存在通常会落到 *os.PathError，可以用 errors.As 取出操作名和路径。

func classify(rootDir, name string) string {
    data, err := ReadWithinRoot(rootDir, name)
    if err == nil {
        // 这里只用长度展示结果，不把文件内容写进日志。
        return fmt.Sprintf("read %d bytes", len(data))
    }

    if errors.Is(err, ErrEmptyName) {
        // 业务层可以提示调用方补充文件名。
        return "missing file name"
    }

    var pathErr *os.PathError
    if errors.As(err, &pathErr) {
        // 保留底层 Op 和 Path，便于区分 open、read 等阶段。
        return fmt.Sprintf("path error: op=%s path=%s", pathErr.Op, pathErr.Path)
    }
    return "unexpected file error"
}

os.Root 的边界和替代选择

root.Open("../secret.txt")、绝对路径和指向根目录外的符号链接都会被拒绝；根目录内的相对路径和不越界的符号链接可以使用。这个 API 解决的是“文件名可能不可信，但访问范围必须固定”的问题，并不等于完整的沙箱：官方文档提醒它不会自动阻止文件系统边界、Linux bind mount、/proc 特殊文件或 Unix 设备文件。

如果只打开一次文件，可以使用 os.OpenInRoot(rootDir, name)，它等价于创建 Root、打开文件再关闭 Root。需要连续读取多个文件、创建目录或保留根目录句柄时，再显式管理 os.Root。如果路径本来就是程序明确指定的可信输出位置，则普通的 os.Open 可能更直接，不必为了“看起来安全”强行套用 Root。

常见问题

为什么不直接把空字符串改成 .？

因为这会改变输入契约。空字符串通常代表缺参，. 才是明确请求根目录；两者分开后，接口调用和错误统计更容易排查。

为什么要用 %w 而不是 %v？

%w 让 errors.Is 和 errors.As 沿着包装链继续工作。只用 %v 会留下可读文本，却丢掉调用方判断底层错误类型的能力。

什么时候用 os.OpenInRoot？

一次性打开一个根目录内的文件时可以用它；需要共享 Root 进行多次操作时使用 os.OpenRoot 并在生命周期结束时关闭。

最终可以把规则压缩成一句话：空输入在业务边界处理，合法相对路径交给 os.Root 约束，底层错误始终用 %w 传递。这样既限制了访问范围，也没有牺牲排错时需要的错误信息。