Go os.Root Chtimes 文件时间更新有什么限制

我在把文件归档到受限目录时，遇到过一个很容易混淆的问题：文件内容已经写完，但访问时间和修改时间还需要按业务时间补齐。Go 1.25 起，可以先用 os.OpenRoot 固定目录边界，再调用 Root.Chtimes(name, atime, mtime) 更新根目录内文件的两个时间。

它的限制也很明确：name 是 Root 内的相对路径，两个时间分别代表访问时间和修改时间；某个参数使用零值 time.Time{} 时，对应时间保持不变；底层文件系统还可能降低时间精度。

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

先用 OpenRoot 建立目录边界

os.Root 的价值不只是少写一段路径拼接，而是把后续文件操作放进一个明确的目录树。打开 Root 后要及时关闭；传给 Chtimes 的文件名则相对于这个 Root，而不是当前工作目录。

package main

import (
	"fmt"
	"os"
	"time"
)

func updateTimes(rootDir, relativeName string, atime, mtime time.Time) error {
	// Root 固定可访问的目录树，relativeName 只在这棵树内解析。
	root, err := os.OpenRoot(rootDir)
	if err != nil {
		return fmt.Errorf("打开受限目录: %w", err)
	}
	defer root.Close() // 无论更新成功还是失败，都释放 Root 句柄。

	// 两个 time.Time 分别对应访问时间和修改时间。
	if err := root.Chtimes(relativeName, atime, mtime); err != nil {
		return fmt.Errorf("更新 %q 的文件时间: %w", relativeName, err)
	}
	return nil
}

func main() {
	// 这里的路径只是调用示例，不代表某台机器上的真实文件。
	atime := time.Date(2026, time.October, 25, 9, 30, 0, 0, time.UTC)
	mtime := time.Date(2026, time.October, 24, 18, 0, 0, 0, time.UTC)
	if err := updateTimes("/srv/archive", "reports/today.json", atime, mtime); err != nil {
		fmt.Println(err)
	}
}

这里的 rootDir 决定范围，relativeName 决定 Root 内的目标，atime 和 mtime 决定要更新的时间字段。把四者放在同一个函数里，调用方就不容易把绝对路径误当成任意系统路径。

两个时间参数不是一个意思

Root.Chtimes 的签名是：

func (r *Root) Chtimes(name string, atime, mtime time.Time) error

atime 是访问时间，mtime 是修改时间。归档工具通常更关心 mtime，而增量扫描或审计程序可能还会读取 atime。不要把两个参数都填成同一个“业务时间”，除非业务确实要求它们一致。

如果只想更新其中一个时间，可以把另一个参数设为零值：

func touchModified(root *os.Root, name string, modified time.Time) error {
	// 零值 atime 表示保持原访问时间，只调整 mtime。
	return root.Chtimes(name, time.Time{}, modified)
}

零值不是“设置成 Unix 时间起点”，而是“对应字段不修改”。这是批量补时间时最值得写进注释的规则，否则调用者很容易把未使用的参数误填成一个实际时间。

精度、权限和路径错误要分开排查

即使传入了带纳秒的 time.Time，底层文件系统也可能截断或四舍五入到更粗的时间单位。因此不要把文件系统读回的时间与内存中的时间做无条件的纳秒级相等比较。

另一个常见误区是把 Root 当成权限提升工具。Root 只集中表达目录范围，不会替当前进程获得修改文件元数据的权限；目标不存在、运行账户权限不足、相对路径越界，都需要按不同方向处理。

func classifyTimeError(err error) string {
	// 保留标准错误分类，便于上层决定重试、提示还是终止。
	switch {
	case os.IsNotExist(err):
		return "Root 内没有这个目标文件"
	case os.IsPermission(err):
		return "当前进程没有修改文件时间的权限"
	default:
		return "继续查看 *os.PathError 的操作名和路径"
	}
}

在 Unix 平台上，Root 的 Chmod、Chown 和 Chtimes 还存在目标在操作过程中被替换为符号链接的竞态说明。涉及不可信路径或并发改名时，要把这条平台限制写进安全设计，而不是只看函数返回值。

把时间策略封装起来更容易复用

实际项目里，我会把“保留访问时间、更新修改时间”这样的业务意图封装成函数，不让调用方到处构造两个时间参数：

func refreshArchiveTime(rootDir, name string, modified time.Time) error {
	// 业务策略固定为只更新 mtime，atime 使用零值保留。
	if name == "" || name[0] == '/' {
		return fmt.Errorf("文件名必须是非空相对路径")
	}

	root, err := os.OpenRoot(rootDir)
	if err != nil {
		return fmt.Errorf("打开归档目录: %w", err)
	}
	defer root.Close() // Root 拥有系统资源，函数退出时统一清理。

	if err := root.Chtimes(name, time.Time{}, modified); err != nil {
		return fmt.Errorf("刷新归档时间: %w", err)
	}
	return nil
}

这个封装固定了三件事：范围由 OpenRoot 决定，输入必须是相对路径，时间策略只修改 mtime。如果未来要同时更新两个字段，只需在一个地方调整策略。

常见问题

Root.Chtimes 可以传绝对路径吗？

不要把它当作任意绝对路径 API 使用。它的输入应当是 Root 内的路径；如果路径指向 Root 外，应该按边界错误处理。

为什么设置了纳秒时间，读回来却不完全一样？

文件系统可能只保存更粗的时间精度。比较结果时应使用业务允许的误差范围，或先明确存储介质的精度。

零值时间会把时间改成 1970 年吗？

不会。标准库对 Chtimes 的约定是：对应参数为零值时保持该文件时间不变。

总结

用 os.OpenRoot 建立目录边界，用 Root 内相对路径定位文件，用 atime 和 mtime 分别表达两个时间；只改一个字段时，另一个参数使用零值。最后把文件系统精度、进程权限、路径越界和平台竞态分开记录，才能让 Root.Chtimes 的行为在归档、迁移和审计场景中保持可解释。