用 Python 生成文件清单：大小、哈希与错误记录

整理项目交付物或归档目录时，只看文件名往往不够：同名文件可能内容不同，复制过程也可能漏文件。一个包含相对路径、字节数和 SHA-256 的 CSV 清单，可以帮助我们核对目录内容。下面的脚本只读取文件并写出清单，不会修改源目录。

实现思路

1. 递归遍历指定目录，只处理普通文件；符号链接单独跳过，避免意外走出目标目录或形成循环。
2. 分块读取文件计算 SHA-256，避免把大文件一次性加载到内存。
3. 每处理一个文件就写一行 CSV。读取失败时记录错误，整批任务继续运行。
4. 把清单输出到扫描目录之外，避免脚本把自己生成的 CSV 也扫进去。

完整脚本

from pathlib import Path
import argparse
import csv
import hashlib


def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as stream:
        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def build_manifest(root: Path, output: Path) -> None:
    root = root.resolve(strict=True)
    output = output.resolve()
    if not root.is_dir():
        raise ValueError(f"不是目录: {root}")
    if output == root or root in output.parents:
        raise ValueError("请把 CSV 输出到扫描目录之外")

    output.parent.mkdir(parents=True, exist_ok=True)
    with output.open("w", newline="", encoding="utf-8-sig") as stream:
        writer = csv.writer(stream)
        writer.writerow(["relative_path", "size_bytes", "sha256", "error"])
        for path in sorted(root.rglob("*")):
            if path.is_symlink() or not path.is_file():
                continue
            relative = path.relative_to(root).as_posix()
            try:
                size = path.stat().st_size
                digest = sha256_file(path)
                writer.writerow([relative, size, digest, ""])
            except OSError as exc:
                writer.writerow([relative, "", "", str(exc)])


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("directory", type=Path)
    parser.add_argument("output_csv", type=Path)
    args = parser.parse_args()
    build_manifest(args.directory, args.output_csv)

运行示例：

python manifest.py ./project ./project-manifest.csv

这里的第二个参数位于扫描目录之外。CSV 使用 utf-8-sig 编码，便于在常见表格软件中打开中文文件名。若文件在扫描过程中被其他程序修改，记录的大小和哈希可能来自不同时间点；需要严格一致性时，应先对目录做快照或暂停写入，再生成清单。对于文件数量极多的目录，还可以把排序改为流式遍历，以减少内存占用。

这份清单适合用于交付前核对和归档记录。校验时重新计算目标目录的哈希，与清单中的相对路径和哈希逐项比较即可。