Go Root.Link 怎样在受限目录内创建同目录硬链接

如果程序要在用户上传目录、插件目录或解压工作区中创建硬链接，直接使用全局路径的 os.Link，就很难把“源路径”和“目标路径”都限制在同一个根目录里。Go 的 os.Root 提供了这个边界，Root.Link(oldname, newname) 再把两个相对路径解释为根目录内的路径。

官方文档：https://pkg.go.dev/os#Root.Link

核心写法是先用 os.OpenRoot 打开目录，再调用 root.Link("source.txt", "backup/source.txt")。两个参数都相对这个 Root，创建的是同一文件的第二个硬链接目录项；如果路径越过根目录，调用应返回错误。

先把 Root.Link 的模式命名清楚

这里采用的是“根目录句柄 + 相对名称”的边界模式。os.OpenRoot 打开一个目录并返回 *os.Root，之后的 Root 方法只接受根目录树下的名称。Root.Link 的两个参数分别表示已有目录项和新目录项，二者都不应被理解成系统任意位置的路径。

这个模式解决的是文件操作的范围问题，而不是硬链接本身的复制问题。硬链接创建成功后，旧名字和新名字共享同一个文件内容与元数据对象；修改其中一个名字打开的文件，另一名字看到的仍是同一文件。

用相对路径准备受限目录

先把业务目录交给 os.OpenRoot，然后在这个 Root 上创建或打开文件。示例只保留本篇需要的最小边界：根目录外的路径不作为输入，文件名由程序内部决定，Root 使用完后关闭。

package main

import (
	"fmt"
	"os"
)

func prepareRoot(dir string) (*os.Root, error) {
	// OpenRoot 把后续 Root 方法的访问范围固定在 dir 对应的目录树内。
	root, err := os.OpenRoot(dir)
	if err != nil {
		return nil, fmt.Errorf("打开受限目录: %w", err)
	}
	return root, nil
}

这里的 dir 是建立边界的入口，oldname 和 newname 则是边界内的相对名称。不要先把用户输入拼成绝对路径，再以为传给 Root.Link 后还能恢复边界语义；Root 方法的参数契约本身就是相对路径。

调用 Root.Link 创建同一文件的第二个目录项

硬链接适合“同一份文件需要多个目录入口”的场景，例如在归档工作区里保留一个固定名称，同时把它放入按日期组织的目录。下面的代码用 root.WriteFile 准备源文件，再用 root.Link 创建目标项。代码展示的是接口关系，实际项目应根据业务决定目录是否已存在。

package main

import (
	"fmt"
	"os"
)

func createHardLink(root *os.Root) error {
	// WriteFile 的 name 也是 Root 内相对路径；这里先准备一个可链接的源文件。
	if err := root.WriteFile("source.txt", []byte("same file object\n"), 0o640); err != nil {
		return fmt.Errorf("写入源文件: %w", err)
	}

	// oldname 与 newname 都相对 root；Link 不会复制文件内容。
	if err := root.Link("source.txt", "alias.txt"); err != nil {
		return fmt.Errorf("创建硬链接: %w", err)
	}
	return nil
}

func main() {
	root, err := os.OpenRoot("./workspace")
	if err != nil {
		panic(err)
	}
	defer root.Close() // Root 持有目录句柄，任务结束后释放它。

	if err := createHardLink(root); err != nil {
		panic(err)
	}
}

核对这段代码时抓住两点：source.txt 和 alias.txt 是目录项名称，不是两份独立内容；同时，root.Link 只负责创建链接，目标父目录必须先满足业务的目录准备条件。

别把“创建成功”误解成“复制完成”

硬链接与复制文件的结果不同。复制会产生新的文件对象，硬链接只是为原有文件对象增加一个名字。因而判断结果时，应围绕“两个名字是否指向同一对象”来设计后续操作，而不是读取两份内容再比较字节。

如果业务要验证目录项是否存在，可以用 Root 的其他方法读取或统计信息；但这属于结果检查，不改变 Link 的语义。删除一个目录项也不会自动删除仍被其他硬链接引用的文件对象，这是硬链接模型带来的生命周期后果。

import "fmt"

func linkAndRead(root *os.Root) ([]byte, error) {
	// 先创建第二个目录项；目标名称不能与已有目录项冲突。
	if err := root.Link("source.txt", "alias.txt"); err != nil {
		return nil, fmt.Errorf("建立别名: %w", err)
	}

	// 通过新名称读取，验证的是同一文件对象的可访问性，而不是截图式输出。
	data, err := root.ReadFile("alias.txt")
	if err != nil {
		return nil, fmt.Errorf("读取链接名称: %w", err)
	}
	return data, nil
}

示例中的判断只说明新目录项可以被 Root 访问。不要把“读取到相同文本”写成跨平台硬链接身份证明；如果业务必须确认文件对象身份，应按目标平台提供的文件信息能力设计检查。

符号链接源文件与平台边界

Root.Link 的文档对符号链接源文件有特别说明：如果 oldname 是符号链接，创建的是指向这个符号链接本身的硬链接，而不是自动跟随到它的目标文件。这一点和某些平台上普通 Link 的行为可能不同，不能在代码里用“链接源一定会被解引用”的假设。

此外，官方文档说明 GOOS=js 下，如果源文件是符号链接，Root.Link 会返回错误。路径边界也仍然有效：oldname 或 newname 试图走出 Root 的目录树时，应把返回错误作为输入不符合边界的信号处理。

什么时候用 Root.Link，什么时候用普通 os.Link

如果程序已经明确掌握两个全局路径，并且不需要把访问限制在某个目录树内，普通 os.Link 的表达更直接；如果路径来自上传、插件、归档或租户目录，Root 模式更容易把“可访问范围”写进 API 边界。

这不是“Root.Link 更安全、os.Link 更危险”的绝对排序，而是把目录边界放在不同层次管理。选 Root.Link 的主要理由，是让边界和文件操作使用同一个对象表达，减少调用点之间的路径假设。

常见问题

Root.Link 的两个参数可以写绝对路径吗？

不应这样设计。Root 方法的名称参数相对 Root 解释；把绝对路径或包含越界意图的路径交给它，应该按错误输入处理，而不是依赖平台差异。

硬链接会复制文件内容吗？

不会。它增加的是同一文件对象的目录项。若业务需要独立副本，应使用复制逻辑，而不是把硬链接当成备份文件。

为什么源文件是符号链接时结果和预期不同？

Root.Link 的源路径语义是链接自身，不是自动跟随到目标文件；同时 GOOS=js 对符号链接源有额外错误边界。需要跨平台部署时，应把这个分支明确写进错误处理和测试矩阵。

总结

Root.Link 的价值在于把硬链接操作放进一个明确的目录边界：先用 os.OpenRoot 得到 Root，再用两个相对名称表达源目录项和目标目录项。写代码时重点检查路径是否仍在 Root 内、目标项是否会冲突、源文件是否为符号链接，以及目标 GOOS 是否改变了行为。这样，硬链接的文件对象语义和目录访问边界就不会混在一起。