Documentation
¶
Overview ¶
Package fs 提供文件系统操作工具，支持文件和目录的复制、移动、检查等功能。
复制功能支持的场景
Copy 和 CopyEx 函数支持以下复制场景：
【文件复制】
- Copy("a.txt", "b.txt") → 创建 b.txt（精确路径模式）
- Copy("a.txt", "existingDir") → 创建 existingDir/a.txt（自动追加文件名）
- Copy("a.txt", "existingDir/") → 创建 existingDir/a.txt（自动追加文件名）
- Copy("a.txt", "newDir/b.txt") → 创建 newDir/b.txt（自动创建父目录）
【目录复制】
- Copy("dirA", "dirB") → 创建 dirB/（dirB 不存在时）
- Copy("dirA", "existingDir") → 创建 existingDir/dirA/（自动追加目录名）
- Copy("dirA", "existingDir/") → 创建 existingDir/dirA/（自动追加目录名）
- Copy("dirA", "newDir/subDir") → 创建 newDir/subDir/（自动创建父目录）
【特殊类型】
- 符号链接：Linux/macOS 保留链接，Windows 当作普通文件复制
- 特殊文件：设备文件、命名管道等（仅 Unix 系统）
移动功能
Move 和 MoveEx 函数（见 move.go）支持文件和目录移动，移动规则与复制相同。 注意：移动操作通过复制+删除实现，支持跨文件系统移动。
智能路径处理规则：
- 如果目标路径是已存在的目录，自动追加源文件名/目录名
- 如果目标路径不存在或不是目录，使用精确路径模式
覆盖控制：
- Copy() / Move() 函数默认不允许覆盖已存在的目标
- CopyEx() / MoveEx() 函数可通过 overwrite 参数控制是否允许覆盖
原子性保证：
- 文件复制使用临时文件 + os.Rename 保证原子性
- 覆盖时先备份原文件，失败时自动恢复
【已知限制】
- Windows 上复制指向目录的符号链接会失败 原因：Windows 符号链接需要管理员权限，当符号链接指向目录时， 内部调用 copyFile 会因目标不是普通文件而返回错误。 建议：Windows 用户使用快捷方式而非符号链接，或手动处理此类特殊情况。
Index ¶
- func Collect(targetPath string, recursive bool) ([]string, error)
- func Copy(src, dst string) error
- func CopyEx(src, dst string, overwrite bool) (err error)
- func Exists(path string) bool
- func GetDefaultBinPath() string
- func GetExecutablePath() string
- func GetSize(path string) (int64, error)
- func GetUserHomeDir() string
- func IsDir(path string) bool
- func IsFile(path string) bool
- func IsHidden(path string) bool
- func IsOctPerm(permission string) bool
- func IsReadOnly(path string) bool
- func Move(src, dst string) error
- func MoveEx(src, dst string, overwrite bool) (err error)
- func OctStrToMode(octalStr string) (os.FileMode, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Collect ¶
Collect 收集指定路径下的所有文件 用于收集文件或目录中的文件，支持通配符匹配和递归遍历
参数:
- targetPath: 目标路径，支持通配符(*?[]{})
- recursive: 是否递归遍历目录
返回:
- []string: 收集到的文件路径切片
- error: 收集失败时返回错误
func Copy ¶ added in v0.0.8
Copy 通用复制函数，自动判断源路径类型并调用相应的复制函数 支持复制普通文件、目录、符号链接和特殊文件 (设备文件、命名管道等)
参数:
- src: 源路径 (支持文件、目录、符号链接、特殊文件)
- dst: 目标路径（支持文件、目录，自动创建父目录）
返回:
- error: 复制失败时返回错误，如果目标已存在则返回错误
func CopyEx ¶ added in v0.0.8
CopyEx 通用复制函数 (可控制是否覆盖)，自动判断源路径类型并调用相应的复制函数 支持复制普通文件、目录、符号链接和特殊文件 (设备文件、命名管道等)
参数:
- src: 源路径 (支持文件、目录、符号链接、特殊文件)
- dst: 目标路径（支持文件、目录，自动创建父目录）
- overwrite: 是否允许覆盖已存在的目标文件/目录
返回:
- error: 复制失败时返回错误
智能路径处理:
- 如果 dst 是已存在的目录，会自动追加源文件名/目录名
- 例如: Copy("a.txt", "existingDir") → 创建 existingDir/a.txt
- 例如: Copy("dirA", "existingDir") → 创建 existingDir/dirA/
func Exists ¶
Exists 检查指定路径的文件或目录是否存在 用于验证文件系统中指定路径是否存在，权限错误等异常情况视为不存在
参数:
- path: 要检查的路径
返回:
- bool: 文件或目录存在返回true，否则返回false
func GetDefaultBinPath ¶
func GetDefaultBinPath() string
GetDefaultBinPath 返回默认bin路径 用于获取Go程序的默认bin路径，采用多级回退策略确保总能返回有效路径
返回:
- string: 默认bin路径，优先级为GOPATH/bin > 用户主目录/go/bin > 当前工作目录/bin
func GetExecutablePath ¶
func GetExecutablePath() string
GetExecutablePath 获取程序的绝对安装路径 用于获取当前可执行文件的绝对路径，提供多级降级策略确保总能返回路径
返回:
- string: 程序的绝对路径，失败时降级为相对路径
func GetSize ¶
GetSize 获取文件或目录的大小 用于计算文件或目录的总字节数，目录会递归计算所有普通文件的大小
参数:
- path: 文件或目录路径
返回:
- int64: 文件或目录的总大小(字节)
- error: 路径不存在或访问失败时返回错误
func GetUserHomeDir ¶
func GetUserHomeDir() string
GetUserHomeDir 获取用户家目录 用于获取用户家目录路径，提供多级降级策略确保总能返回有效路径
返回:
- string: 用户家目录路径，失败时依次降级为工作目录或当前目录
func IsHidden ¶
IsHidden 判断文件或目录是否为隐藏 用于跨平台检查文件或目录的隐藏属性
参数:
- path: 文件或目录路径
返回:
- bool: 文件为隐藏返回true，否则返回false
func IsOctPerm ¶
IsOctPerm 检查输入的权限是否是合法的4位八进制数 用于验证权限字符串格式是否符合八进制权限规范
参数:
- permission: 输入的权限字符串，例如 "0755" 或 "0644"
返回:
- bool: 权限格式合法返回true，否则返回false
func IsReadOnly ¶
IsReadOnly 判断文件或目录是否为只读 用于跨平台检查文件或目录的只读属性
参数:
- path: 文件或目录路径
返回:
- bool: 文件为只读返回true，否则返回false
func Move ¶ added in v0.0.14
Move 通用移动函数，将文件或目录移动到目标位置 支持移动普通文件、目录、符号链接和特殊文件 优先使用 os.Rename（同文件系统内），失败时降级使用复制+删除（支持跨文件系统）
参数:
- src: 源路径 (支持文件、目录、符号链接、特殊文件)
- dst: 目标路径（支持文件、目录，自动创建父目录）
返回:
- error: 移动失败时返回错误，如果目标已存在则返回错误
func MoveEx ¶ added in v0.0.14
MoveEx 通用移动函数 (可控制是否覆盖)，将文件或目录移动到目标位置 支持移动普通文件、目录、符号链接和特殊文件 优先使用 os.Rename（同文件系统内），失败时降级使用复制+删除（支持跨文件系统）
参数:
- src: 源路径 (支持文件、目录、符号链接、特殊文件)
- dst: 目标路径（支持文件、目录，自动创建父目录）
- overwrite: 是否允许覆盖已存在的目标文件/目录
返回:
- error: 移动失败时返回错误
智能路径处理:
- 如果 dst 是已存在的目录，会自动追加源文件名/目录名
- 例如: Move("a.txt", "existingDir") → 移动到 existingDir/a.txt
- 例如: Move("dirA", "existingDir") → 移动到 existingDir/dirA/
移动策略:
- 优先使用 os.Rename（原子操作，同文件系统内高效）
- rename 失败时降级使用 CopyEx + os.RemoveAll（支持跨文件系统）
func OctStrToMode ¶
OctStrToMode 将4位八进制字符串权限转换为 os.FileMode 类型 用于将八进制权限字符串转换为Go标准库的文件权限类型
参数:
- octalStr: 4位八进制字符串，例如 "0755" 或 "0644"
返回:
- os.FileMode: 转换后的文件权限
- error: 输入不合法时返回错误
示例:
mode, err := OctStrToMode("0755")
if err != nil {
log.Fatal(err)
}
fmt.Println(mode) // 输出: -rwxr-xr-x
Types ¶
This section is empty.
Source Files