Go 创建多层目录为什么不能只用 Mkdir

给日志、缓存或导出文件准备目录时，最容易踩的坑是把 os.Mkdir 当成“自动创建整条路径”。它只负责创建传入的最后一级目录；如果 data/archive 还不存在，直接创建 data/archive/2026 就会因为父目录缺失而失败。需要补齐多层路径时，应使用 os.MkdirAll。

判断很简单：只创建一个已经存在父目录下的目录，用 Mkdir；目录树可能尚未准备好，或者同一初始化逻辑会重复执行，用 MkdirAll。后者在目标已经是目录时返回 nil，但不会把同名文件当成目录。

Mkdir 只处理最后一级，MkdirAll 才处理目录树

把路径拆成“父目录 + 最后一级”就能看懂两者的差异。os.Mkdir("data/archive/2026", 0o750) 的前提是 data/archive 已经存在且确实是目录；它不会替你逐层补齐父目录。os.MkdirAll 则会创建路径中缺失的必要父目录，并且目标路径已经是目录时不报错。

因此，单层创建可以这样写；错误要保留路径信息，方便定位到底是哪一级出了问题：

package main

import (
    "fmt"
    "os"
)

func createOneDir() error {
    // Mkdir 只创建最后一级，data/archive 必须先存在。
    if err := os.Mkdir("data/archive/2026", 0o750); err != nil {
        return fmt.Errorf("创建单层目录: %w", err)
    }
    return nil
}

func createDirTree() error {
    // MkdirAll 会补齐 data 与 data/archive 等缺失父目录。
    if err := os.MkdirAll("data/archive/2026", 0o750); err != nil {
        return fmt.Errorf("创建目录树: %w", err)
    }
    return nil
}

perm 不是最终权限，umask 会继续参与计算

0o750 这类写法表示创建请求中的权限位：所有者可读、可写、可进入，所属组可读、可进入，其他用户没有权限。官方文档说明，Mkdir 和 MkdirAll 使用的是 umask 之前的权限位，所以不要把传入的 perm 直接当作文件系统最终显示值。

还要注意，目录的“进入”权限是执行位。即使目录列表看起来可读，没有对应的执行权限，进程也可能无法进入目录或访问其中的文件。生产代码通常把权限选择写成业务意图：共享读取的目录可用 0o755，只允许服务用户和同组进程访问的目录可考虑 0o750，再由部署环境的 umask 做统一收紧。

已存在目录、同名文件和中间路径错误要分开处理

MkdirAll 的幂等性只针对“路径已经是目录”。例如服务启动时每次都执行 os.MkdirAll("var/app/cache", 0o750) 是合理的；但如果 var/app/cache 实际上是一个普通文件，函数仍会返回错误。更早的父路径如果被文件占用，也会阻断后续目录创建。

不要用 strings.Contains(err.Error(), "exist") 这种字符串判断来吞掉异常。创建失败通常带有 *os.PathError，可以用 errors.As 取出结构化信息；是否忽略“已存在”也应由调用的 API 语义决定，而不是统一忽略所有错误。

把目录准备放在写文件之前，形成可重复调用的入口

目录创建最好紧挨着后续写入动作，并把目标路径作为参数传入。这样既不会依赖某次部署手工创建目录，也能让错误明确指出“准备哪个目录”：

package storage

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

func PrepareFile(path string) error {
    dir := filepath.Dir(path)
    // 目录准备可以重复执行；MkdirAll 对已有目录返回 nil。
    if err := os.MkdirAll(dir, 0o750); err != nil {
        return fmt.Errorf("准备文件目录 %q: %w", dir, err)
    }
    // 这里只负责准备目录，文件内容由后续写入逻辑处理。
    return nil
}

调用方仍应检查返回值：如果出现权限不足、路径中存在同名文件、挂载点不可写等情况，继续写文件只会把真正原因埋到后面的错误里。若应用需要确认最终权限，可以在创建后用 os.Stat 读取 FileInfo.Mode().Perm()；这属于部署检查，不是用来替代错误处理。

常见问题

MkdirAll 会覆盖已有目录吗？

不会。目标已经是目录时它返回 nil，不会清空内容，也不会把权限自动改成本次传入的 perm。

只创建一层时能不能总用 MkdirAll？

可以，但要接受它会创建缺失父目录的语义。若父目录必须由部署流程提前提供，使用 Mkdir 更能暴露环境配置错误。

为什么传了 0o755，实际权限却不是 755？

因为权限位还会受到进程 umask 影响；同时也要确认查看权限的用户、平台和挂载文件系统。

记住“单层用 Mkdir，目录树用 MkdirAll，所有返回值都处理”这条判断，绝大多数 Go 创建目录问题就能在写文件前解决。