`hutool.core.io.file`¶

文件工具类，对应 Java cn.hutool.core.io.FileUtil

基于 pathlib.Path 实现，辅以 os 和 shutil。

Module Contents¶

Classes¶

FileUtil

文件工具类，对应 Java cn.hutool.core.io.FileUtil

API¶

class hutool.core.io.file.FileUtil¶

文件工具类，对应 Java cn.hutool.core.io.FileUtil

FILE_SEPARATOR: str = None¶

static is_windows() → bool¶

判断当前操作系统是否为 Windows。

返回:: 是否为 Windows 系统

static exist(path: Union[str, pathlib.Path]) → bool¶

判断文件或目录是否存在。

参数:: path – 文件或目录路径
返回:: 是否存在

static is_dir(path: Union[str, pathlib.Path]) → bool¶

判断是否为目录。

参数:: path – 路径
返回:: 是否为目录

static is_file(path: Union[str, pathlib.Path]) → bool¶

判断是否为文件。

参数:: path – 路径
返回:: 是否为文件

static is_absolute(path: Union[str, pathlib.Path]) → bool¶

判断路径是否为绝对路径。

参数:: path – 路径
返回:: 是否为绝对路径

static is_empty(path: Union[str, pathlib.Path]) → bool¶

文件或目录是否为空。

文件：大小为 0 视为空。
目录：不含任何子项视为空。
路径不存在视为空。

参数:: path – 文件或目录路径
返回:: 是否为空

static file(*names: str) → pathlib.Path¶

根据多个名称段构建文件路径。

例如: FileUtil.file("home", "user", "test.txt")

参数:: names – 路径段
返回:: Path 对象
抛出:: ValueError – 未传入任何路径段时

static touch(path: Union[str, pathlib.Path]) → pathlib.Path¶

创建文件（包括父目录）。

如果文件已存在则只更新访问/修改时间。

参数:: path – 文件路径
返回:: 创建的文件路径

static mkdir(path: Union[str, pathlib.Path]) → pathlib.Path¶

创建目录。

如果目录已存在则直接返回。

参数:: path – 目录路径
返回:: 创建的目录路径

static mkdirs(path: Union[str, pathlib.Path]) → pathlib.Path¶

创建多级目录（与 mkdir 行为一致，支持多级创建）。

参数:: path – 目录路径
返回:: 创建的目录路径

static create_temp_file(prefix: str = 'hutool', suffix: str = '.tmp', parent_dir: Optional[str] = None) → pathlib.Path¶

创建临时文件

参数:

prefix – 文件名前缀
suffix – 文件名后缀（含点号）
parent_dir – 临时文件所在目录，为 None 时使用系统临时目录

返回:

创建的临时文件路径

static del_file(path: Union[str, pathlib.Path]) → bool¶

删除文件或目录

文件：直接删除。
目录：递归删除整个目录树。
路径不存在时返回 True。

返回:: 是否删除成功

static clean(path: Union[str, pathlib.Path]) → bool¶

返回:: 是否清空成功

static copy(src: Union[str, pathlib.Path], dest: Union[str, pathlib.Path], is_override: bool = True) → pathlib.Path¶

复制文件或目录

参数:

src – 源路径
dest – 目标路径
is_override – 是否覆盖已存在的目标

返回:

目标路径

static copy_file(src: Union[str, pathlib.Path], dest: Union[str, pathlib.Path]) → pathlib.Path¶

复制文件。

如果目标目录不存在则自动创建。

参数:

src – 源文件路径
dest – 目标文件路径

返回:

目标文件路径

抛出:

FileNotFoundError – 源文件不存在或不是文件时

static move(src: Union[str, pathlib.Path], dest: Union[str, pathlib.Path], is_override: bool = True) → pathlib.Path¶

移动文件或目录

参数:

src – 源路径
dest – 目标路径
is_override – 是否覆盖已存在的目标

返回:

目标路径

static rename(file: Union[str, pathlib.Path], new_name: str) → pathlib.Path¶

重命名文件或目录

参数:

file – 源文件或目录路径
new_name – 新名称（仅名称部分，不含路径）

返回:

重命名后的路径

static read_string(path: Union[str, pathlib.Path], charset: str = 'utf-8') → str¶

读取文件内容为字符串

参数:

path – 文件路径
charset – 字符编码

返回:

文件内容字符串

static read_bytes(path: Union[str, pathlib.Path]) → bytes¶

读取文件内容为字节数组。

参数:: path – 文件路径
返回:: 字节数据

static read_lines(path: Union[str, pathlib.Path], charset: str = 'utf-8') → List[str]¶

读取文件内容为字符串列表（每行一个元素，保留换行符）。

参数:

path – 文件路径
charset – 字符编码

返回:

行列表

static read_utf8_lines(path: Union[str, pathlib.Path]) → List[str]¶

以 UTF-8 编码读取文件的每一行（去除行尾换行符）。

参数:: path – 文件路径
返回:: 行列表

static read_lines_str(path: Union[str, pathlib.Path], charset: str = 'utf-8') → List[str]¶

读取文件的每一行，去除行尾换行符。

参数:

path – 文件路径
charset – 字符编码

返回:

行列表

static write_string(path: Union[str, pathlib.Path], content: str, charset: str = 'utf-8', is_append: bool = False) → pathlib.Path¶

写入字符串到文件

参数:

path – 文件路径
content – 写入内容
charset – 字符编码
is_append – 是否追加模式

返回:

文件路径

static write_bytes(path: Union[str, pathlib.Path], data: bytes, is_append: bool = False) → pathlib.Path¶

写字节数组到文件

参数:

path – 文件路径
data – 字节数据
is_append – 是否追加模式

返回:

文件路径

static write_lines(path: Union[str, pathlib.Path], lines: list, charset: str = 'utf-8', is_append: bool = False) → pathlib.Path¶

写入行列表到文件

每个元素后自动追加换行符。

参数:

path – 文件路径
lines – 行列表
charset – 字符编码
is_append – 是否追加模式

返回:

文件路径

static append_string(path: Union[str, pathlib.Path], content: str, charset: str = 'utf-8') → pathlib.Path¶

追加字符串到文件末尾

参数:

path – 文件路径
content – 追加内容
charset – 字符编码

返回:

文件路径

static append_lines(path: Union[str, pathlib.Path], lines: list, charset: str = 'utf-8') → pathlib.Path¶

追加行列表到文件末尾

参数:

path – 文件路径
lines – 行列表
charset – 字符编码

返回:

文件路径

static loop_files(path: Union[str, pathlib.Path], max_depth: Optional[int] = None, file_filter: Optional[Callable[[pathlib.Path], bool]] = None) → List[pathlib.Path]¶

递归遍历目录下的所有文件

参数:

path – 根目录路径
max_depth – 最大递归深度，None 表示不限制
file_filter – 文件过滤函数，返回 True 保留

返回:

符合条件的文件路径列表

static _walk_files(directory: pathlib.Path, current_depth: int, max_depth: Optional[int], file_filter: Optional[Callable[[pathlib.Path], bool]], result: List[pathlib.Path]) → None¶: 递归遍历的内部实现

static list_file_names(path: Union[str, pathlib.Path]) → List[str]¶

列出目录下的文件名（仅直接子文件，不含子目录内的文件）

参数:: path – 目录路径
返回:: 文件名列表（不含路径前缀）

static walk_files(path: Union[str, pathlib.Path], consumer: Callable[[pathlib.Path], None]) → None¶

递归遍历文件并对每个文件执行操作。

参数:

path – 根目录路径
consumer – 对每个文件执行的回调函数

static size(path: Union[str, pathlib.Path]) → int¶

获取文件大小（字节）。

参数:: path – 文件或目录路径
返回:: 大小（字节）
抛出:: FileNotFoundError – 路径不存在时

static last_modified_time(path: Union[str, pathlib.Path]) → datetime.datetime¶

获取文件最后修改时间

返回:: 最后修改时间的 datetime 对象

static get_total_lines(path: Union[str, pathlib.Path]) → int¶

获取文件总行数。

参数:: path – 文件路径
返回:: 总行数

static get_name(path: Union[str, pathlib.Path]) → str¶

获取文件名（含扩展名）。

例如: /home/user/test.txt -> test.txt

参数:: path – 文件路径
返回:: 文件名

static get_suffix(path: Union[str, pathlib.Path]) → str¶

获取文件扩展名（不带点号）。

例如: /home/user/test.txt -> txt

如果没有扩展名则返回空字符串。

参数:: path – 文件路径
返回:: 扩展名，无扩展名时返回空字符串

static get_prefix(path: Union[str, pathlib.Path]) → str¶

获取文件名前缀（不含扩展名）。

例如: /home/user/test.txt -> test

参数:: path – 文件路径
返回:: 文件名前缀

static main_name(path: Union[str, pathlib.Path]) → str¶

获取主文件名（同 get_prefix）。

参数:: path – 文件路径
返回:: 主文件名

static normalize(path: Union[str, pathlib.Path]) → str¶

标准化路径，解析 ~ 和相对路径符号。

参数:: path – 原始路径
返回:: 标准化后的路径字符串

static get_tmp_dir_path() → str¶

获取系统临时目录路径（字符串）。

static get_tmp_dir() → pathlib.Path¶

获取系统临时目录（Path 对象）。

返回:: 临时目录 Path 对象

static get_user_home_path() → str¶

获取用户主目录路径（字符串）。

static get_user_home_dir() → pathlib.Path¶

获取用户主目录（Path 对象）。

返回:: 用户主目录 Path 对象

static newer_than(file: Union[str, pathlib.Path], reference: Union[str, pathlib.Path]) → bool¶

判断文件是否比参考文件更新

参数:

file – 待比较的文件
reference – 参考文件

返回:

如果 file 的修改时间晚于 reference 则返回 True

static is_symlink(path: Union[str, pathlib.Path]) → bool¶

判断是否为符号链接。

参数:: path – 路径
返回:: 是否为符号链接

static sub_path(path: Union[str, pathlib.Path], start: int, end: int) → str¶

获取子路径

参数:

path – 源路径
start – 起始索引（含）
end – 结束索引（不含）

返回:

子路径字符串

例如: sub_path(“/home/user/test.txt”, 1, 3) -> “user/test.txt”

static write_utf8_string(path: Union[str, pathlib.Path], content: str) → pathlib.Path¶

以 UTF-8 编码写入字符串到文件。

参数:

path – 文件路径
content – 写入内容

返回:

文件路径

static write_utf8_lines(path: Union[str, pathlib.Path], lines: list) → pathlib.Path¶

以 UTF-8 编码写入多行到文件。

参数:

path – 文件路径
lines – 行列表

返回:

文件路径

static write_utf8_map(path: Union[str, pathlib.Path], map_data: Dict[str, Any], kv_separator: str = '=') → pathlib.Path¶

以 UTF-8 编码将字典写入文件（每行一个 key=value）。

参数:

path – 文件路径
map_data – 字典数据
kv_separator – 键值分隔符，默认 “=”

返回:

文件路径

static write_map(path: Union[str, pathlib.Path], map_data: Dict[str, Any], kv_separator: str = '=', charset: str = 'utf-8') → pathlib.Path¶

将字典写入文件（每行一个 key=value）。

参数:

path – 文件路径
map_data – 字典数据
kv_separator – 键值分隔符，默认 “=”
charset – 字符编码

返回:

文件路径

static append_utf8_string(path: Union[str, pathlib.Path], content: str) → pathlib.Path¶

以 UTF-8 编码追加字符串到文件。

参数:

path – 文件路径
content – 追加内容

返回:

文件路径

static append_utf8_lines(path: Union[str, pathlib.Path], lines: list) → pathlib.Path¶

以 UTF-8 编码追加多行到文件。

参数:

path – 文件路径
lines – 行列表

返回:

文件路径

static read_utf8_string(path: Union[str, pathlib.Path]) → str¶

以 UTF-8 编码读取文件内容为字符串。

参数:: path – 文件路径
返回:: 文件内容字符串

static read_line(path: Union[str, pathlib.Path], line_number: int, charset: str = 'utf-8') → Optional[str]¶

按行号读取文件的指定行（0-based）。

参数:

path – 文件路径
line_number – 行号（从 0 开始）
charset – 字符编码

返回:

指定行的内容，超出范围返回 None

static load_file(path: Union[str, pathlib.Path], charset: str = 'utf-8') → List[str]¶

加载文件内容为行列表（去除行尾换行符）。

参数:

path – 文件路径
charset – 字符编码

返回:

行列表

static load_utf8(path: Union[str, pathlib.Path]) → List[str]¶

以 UTF-8 编码加载文件内容为行列表。

参数:: path – 文件路径
返回:: 行列表

static ls(path: Union[str, pathlib.Path]) → List[pathlib.Path]¶

列出目录内容（仅直接子项）。

参数:: path – 目录路径
返回:: 子项路径列表
抛出:: FileNotFoundError – 路径不存在时

static ext_name(path: Union[str, pathlib.Path]) → str¶

获取文件扩展名（不带点号）。

与 get_suffix() 等价。

参数:: path – 文件路径
返回:: 扩展名，无扩展名时返回空字符串

static get_absolute_path(path: Union[str, pathlib.Path]) → str¶

获取路径的绝对路径字符串。

参数:: path – 文件路径
返回:: 绝对路径字符串

static get_canonical_path(path: Union[str, pathlib.Path]) → str¶

获取路径的规范路径字符串（解析符号链接和 ..）。

参数:: path – 文件路径
返回:: 规范路径字符串

static get_parent(path: Union[str, pathlib.Path], depth: int = 1) → str¶

获取父目录路径（支持多级）。

参数:

path – 文件路径
depth – 向上层级数，默认 1

返回:

父目录路径字符串

static get_type(path: Union[str, pathlib.Path]) → str¶

获取文件类型（通过扩展名推断 MIME 类型）。

参数:: path – 文件路径
返回:: MIME 类型字符串，无法推断时返回空字符串

static get_mime_type(path: Union[str, pathlib.Path]) → str¶

获取文件的 MIME 类型。

参数:: path – 文件路径
返回:: MIME 类型字符串

static is_absolute_path(path: Union[str, pathlib.Path]) → bool¶

判断路径是否为绝对路径。

参数:: path – 路径
返回:: 是否为绝对路径

static last_index_of_separator(path: str) → int¶

获取路径中最后一个分隔符的索引位置。

参数:: path – 路径字符串
返回:: 最后分隔符索引，无分隔符时返回 -1

static path_ends_with(path: Union[str, pathlib.Path], suffix: str) → bool¶

判断路径是否以指定后缀结尾。

参数:

path – 路径
suffix – 后缀字符串

返回:

是否以指定后缀结尾

static is_dir_empty(path: Union[str, pathlib.Path]) → bool¶

判断目录是否为空。

参数:: path – 目录路径
返回:: 是否为空目录

static is_directory(path: Union[str, pathlib.Path]) → bool¶

判断是否为目录。

与 is_dir() 等价。

参数:: path – 路径
返回:: 是否为目录

static is_modified(path: Union[str, pathlib.Path], reference_time: float = 0) → bool¶

判断文件是否在指定时间之后被修改。

参数:

path – 文件路径
reference_time – 参考时间戳（Unix 秒），默认 0 表示始终返回 True

返回:

是否被修改

static file_not_empty(path: Union[str, pathlib.Path]) → bool¶

判断文件是否非空。

参数:: path – 文件路径
返回:: 文件是否存在且大小 > 0

static is_sub_path(parent: Union[str, pathlib.Path], child: Union[str, pathlib.Path]) → bool¶

判断 child 是否为 parent 的子路径。

参数:

parent – 父路径
child – 子路径

返回:

是否为子路径

static path_equals(path1: Union[str, pathlib.Path], path2: Union[str, pathlib.Path]) → bool¶

判断两个路径是否指向同一文件/目录。

参数:

path1 – 第一个路径
path2 – 第二个路径

返回:

是否相等

static content_equals(file1: Union[str, pathlib.Path], file2: Union[str, pathlib.Path], charset: str = 'utf-8') → bool¶

判断两个文件的内容是否相等。

参数:

file1 – 第一个文件路径
file2 – 第二个文件路径
charset – 字符编码（用于文本比较）

返回:

内容是否相等

static mk_parent_dirs(path: Union[str, pathlib.Path]) → pathlib.Path¶

创建文件的父目录（如果不存在）。

参数:: path – 文件路径
返回:: 文件路径

static mkdirs_safely(path: Union[str, pathlib.Path]) → pathlib.Path¶

安全创建目录（如果不存在则创建）。

与 mkdir() 等价。

参数:: path – 目录路径
返回:: 目录路径

static new_file(path: Union[str, pathlib.Path]) → pathlib.Path¶

创建新文件（包含父目录）。

与 touch() 等价。

参数:: path – 文件路径
返回:: 文件路径

static readable_file_size(size: int, precision: int = 1) → str¶

将文件大小转换为可读字符串（如 “1.5 MB”）。

参数:

size – 文件大小（字节）
precision – 小数精度

返回:

可读大小字符串

static copy_content(src: Union[str, pathlib.Path], dest: Union[str, pathlib.Path], is_override: bool = True) → pathlib.Path¶

复制文件内容。

与 copy() 等价。

参数:

src – 源路径
dest – 目标路径
is_override – 是否覆盖

返回:

目标路径

static move_content(src: Union[str, pathlib.Path], dest: Union[str, pathlib.Path]) → pathlib.Path¶

移动文件内容。

与 move() 等价（默认覆盖）。

参数:

src – 源路径
dest – 目标路径

返回:

目标路径

static convert_charset(path: Union[str, pathlib.Path], src_charset: str, dest_charset: str = 'utf-8') → pathlib.Path¶

转换文件编码。

参数:

path – 文件路径
src_charset – 源编码
dest_charset – 目标编码，默认 “utf-8”

返回:

文件路径

static convert_line_separator(path: Union[str, pathlib.Path], separator: str = '\n') → pathlib.Path¶

转换文件的换行符。

参数:

path – 文件路径
separator – 目标换行符（"\n"、"\r\n"、"\r"）

返回:

文件路径

static copy_files_from_dir(src_dir: Union[str, pathlib.Path], dest_dir: Union[str, pathlib.Path], is_override: bool = True) → List[pathlib.Path]¶

从源目录复制所有文件到目标目录（不含子目录结构）。

参数:

src_dir – 源目录路径
dest_dir – 目标目录路径
is_override – 是否覆盖已存在的文件

返回:

复制的文件路径列表

static check_slip(file_path: Union[str, pathlib.Path]) → None¶

检查路径是否存在路径穿越（.. 攻击）。

直接分析原始路径字符串中的 .. 段，不做 resolve，确保任何包含目录穿越的路径都能被检测到。

参数:: file_path – 文件路径
抛出:: ValueError – 存在路径穿越时抛出

static checksum(path: Union[str, pathlib.Path], algorithm: str = 'md5') → str¶

计算文件的校验和。

参数:

path – 文件路径
algorithm – 哈希算法（”md5”、”sha1”、”sha256” 等）

返回:

校验和的十六进制字符串

static checksum_crc32(path: Union[str, pathlib.Path]) → int¶

计算文件的 CRC32 校验值。

参数:: path – 文件路径
返回:: CRC32 校验值（有符号整数）

static clean_empty(path: Union[str, pathlib.Path]) → int¶

参数:: path – 根目录路径
返回:: 清理的项目数

static clean_invalid(path: Union[str, pathlib.Path]) → int¶

清理目录下文件名含无效字符的文件。

参数:: path – 根目录路径
返回:: 清理的文件数

static contains_invalid(name: str) → bool¶

判断文件名是否包含无效字符。

参数:: name – 文件名
返回:: 是否包含无效字符

static tail(path: Union[str, pathlib.Path], lines: int = 10, charset: str = 'utf-8', handler: Optional[Callable[[str], None]] = None) → List[str]¶

读取文件最后 N 行。

使用反向读取实现，不会将整个文件加载到内存。

参数:

path – 文件路径
lines – 返回的行数，默认 10
charset – 字符编码，默认 “utf-8”
handler – 行处理器回调函数（每行调用一次），可选

返回:

最后 N 行的列表（不含行尾换行符）

hutool.core.io.file¶

Module Contents¶

Classes¶

API¶

`hutool.core.io.file`¶