Python os.listdir() 方法（建议收藏）

Python os.listdir() 方法：文件夹内容的“探照灯”

在日常开发中，我们经常需要读取某个目录下的所有文件和子目录，比如批量处理图片、整理日志文件、自动化备份等场景。这时候，Python 的 os.listdir() 方法就显得尤为重要。它就像一个“探照灯”，能照亮你指定路径下的所有内容，让你清楚地知道里面有哪些文件和文件夹。

这个方法简单、高效，是操作系统交互的基础工具之一。尤其对于初学者来说，掌握它不仅能快速上手文件操作，还能为后续学习 os.path、glob、pathlib 等模块打下坚实基础。

本文将带你从零开始，深入理解 os.listdir() 的使用方法、常见陷阱和实用技巧，帮助你在项目中更从容地处理文件系统。

什么是 os.listdir() 方法？

os.listdir() 是 Python 标准库 os 模块中的一个函数，用于获取指定目录下的所有文件和子目录的名称列表。它返回的是一个 list 类型的数据，每个元素都是字符串，表示该目录下的一个条目。

重要提示：它只列出当前目录的内容，不会递归进入子目录。如果你需要遍历整个目录树，那就要配合 os.walk() 或 pathlib.Path.rglob() 使用。

基本语法

os.listdir(path)

path：要查询的目录路径，可以是相对路径（如 ./data）或绝对路径（如 /home/user/documents）。
返回值：一个包含目录下所有条目名称的列表（字符串类型）。

示例：查看当前目录内容

import os

files_and_dirs = os.listdir()

for item in files_and_dirs:
    print(item)

注释：

import os 是使用 os.listdir() 的前提，必须导入模块。

os.listdir() 不传参数时，默认返回当前工作目录的内容。

循环遍历列表，逐个打印每个条目名称，便于观察结果。

如何指定目录路径？

在实际项目中，我们通常不会只查看当前目录。这时就需要传入具体的路径参数。

示例：查看指定目录内容

import os

target_dir = "/path/to/your/folder"

contents = os.listdir(target_dir)

print(f"目录 {target_dir} 下的条目：")
for item in contents:
    print(f"  - {item}")

注释：

target_dir 可以是绝对路径或相对路径。

如果路径不存在或无权限访问，会抛出 FileNotFoundError 或 PermissionError 异常。

建议在使用前用 os.path.exists() 检查路径是否存在，避免程序崩溃。

如何区分文件和文件夹？

os.listdir() 只返回名称，不会告诉你它们是文件还是文件夹。要判断，我们需要配合 os.path 模块中的函数。

使用 os.path.isdir() 和 os.path.isfile()

import os

dir_path = "./my_project"

items = os.listdir(dir_path)

print(f"在 {dir_path} 中的条目：")

for item in items:
    full_path = os.path.join(dir_path, item)  # 拼接完整路径

    if os.path.isdir(full_path):
        print(f"📁 {item} (目录)")
    elif os.path.isfile(full_path):
        print(f"📄 {item} (文件)")
    else:
        print(f"🔗 {item} (其他类型，如链接)")

注释：

os.path.join() 用于安全拼接路径，避免因系统差异（Windows 用 \，Linux 用 /）导致问题。

os.path.isdir() 判断是否为目录，os.path.isfile() 判断是否为普通文件。

os.path.islink() 可用于判断符号链接，但本例暂未使用。

常见问题与解决方案

1. 路径不存在怎么办？

import os

def list_dir_safely(path):
    if not os.path.exists(path):
        print(f"❌ 路径不存在：{path}")
        return []

    try:
        return os.listdir(path)
    except PermissionError:
        print(f"❌ 无权限访问路径：{path}")
        return []

result = list_dir_safely("/tmp/protected_folder")
if result:
    print("✅ 成功获取内容：")
    for item in result:
        print(f"  - {item}")

注释：

先用 os.path.exists() 检查路径是否存在。

使用 try-except 捕获权限错误，提升程序健壮性。

返回空列表表示失败，便于后续逻辑处理。

2. 如何过滤特定类型的文件？

假设你想只列出 .txt 文件，可以结合列表推导式：

import os

directory = "./documents"

txt_files = [f for f in os.listdir(directory) if f.endswith(".txt")]

print("找到的 .txt 文件：")
for file in txt_files:
    print(f"  - {file}")

注释：

f.endswith(".txt") 是字符串方法，判断文件名是否以 .txt 结尾。

列表推导式简洁高效，是 Python 中推荐的写法。

可扩展为其他格式，如 .jpg、.py、.log 等。

3. 为什么有些文件名显示乱码？

在 Windows 系统中，如果文件名包含中文且编码不一致，可能出现乱码问题。建议统一使用 UTF-8 编码。

import os

def list_with_utf8(path):
    try:
        # 有些系统需要显式编码处理
        items = os.listdir(path)
        return [item.encode('utf-8').decode('utf-8') for item in items]
    except Exception as e:
        print(f"编码处理失败：{e}")
        return []

files = list_with_utf8("./中文文件夹")
for f in files:
    print(f"  - {f}")

注释：

此方法适用于极少数因系统编码不一致导致乱码的场景。

大多数现代 Python 3 环境默认支持 UTF-8，无需额外处理。

建议项目中统一使用 UTF-8 编码，避免编码问题。

实用场景：批量重命名文件

想象一个常见需求：你有一个包含 100 个图片的文件夹，想把所有 .jpg 文件名改为 image_001.jpg、image_002.jpg 这样的格式。

import os

def rename_images(directory):
    # 获取所有 .jpg 文件
    jpg_files = [f for f in os.listdir(directory) if f.lower().endswith(".jpg")]

    if not jpg_files:
        print("⚠️ 没有找到 .jpg 文件")
        return

    # 排序，确保顺序一致
    jpg_files.sort()

    # 重命名
    for i, old_name in enumerate(jpg_files, start=1):
        new_name = f"image_{i:03d}.jpg"  # 格式化为 image_001.jpg
        old_path = os.path.join(directory, old_name)
        new_path = os.path.join(directory, new_name)

        try:
            os.rename(old_path, new_path)
            print(f"✅ 重命名：{old_name} → {new_name}")
        except OSError as e:
            print(f"❌ 重命名失败：{old_name} -> {new_name}，错误：{e}")

rename_images("./photos")

注释：

f.lower().endswith(".jpg") 防止大小写问题（如 .JPG）。

enumerate(..., start=1) 从 1 开始编号。

f"{i:03d}" 保证编号为三位数（001、002）。

os.rename() 用于文件重命名，是 os 模块的另一个常用函数。

总结与进阶建议

Python os.listdir() 方法虽然简单，却是文件系统操作的起点。它功能明确、性能良好，适合大多数基础场景。

核心要点回顾：

它返回目录下所有条目的名称列表，不包含路径。
必须导入 os 模块。
无法区分文件与目录，需配合 os.path 使用。
注意路径权限和存在性检查。
可结合列表推导式实现高效过滤。

进阶建议：

对于复杂路径操作，推荐使用 pathlib.Path（Python 3.4+），语法更现代、更直观。
若需递归遍历目录，使用 os.walk() 或 pathlib.Path.rglob()。
在处理大量文件时，考虑使用 glob 模块进行通配符匹配。

Python os.listdir() 方法，就像你打开文件夹时第一眼看到的“清单”。它不解释每个文件是什么，但它告诉你“这里有谁”。掌握它，你就拥有了掌控文件系统的钥匙。从今天开始，别再手动数文件了，让代码替你完成这份工作。