PHP不支持直接处理含冒号的文件名，因冒号被误判为流封装器分隔符导致rename等函数报错；应先清洗非法字符再操作，Windows ADS需规避而非处理。
PHP 本身不直接处理文件系统中含冒号 : 的文件名——因为绝大多数操作系统（Windows 除外）根本不允许在文件名里用冒号，而 Windows 下虽然支持，但 PHP 的 fopen、rename 等函数在遇到含 : 的路径时，极大概率会误判为协议前缀（如 file:// 或 php://），导致操作失败或静默出错。
PHP rename() 处理含冒号文件名直接报错的原因
当你调用 rename('old:name.txt', 'new:name.txt')，PHP 底层会把 : 当作流封装器分隔符。例如 old:name.txt 被解析成「封装器 old + 资源路径 name.txt」，而 old 并非合法封装器，于是触发警告：Warning: rename(): Unable to find the wrapper "old"。
- Linux/macOS 文件系统（ext4、APFS 等）完全禁止
:出现在文件名中，该问题实际不会发生 - Windows NTFS 允许
:，但仅用于创建「备用数据流（ADS）」，比如readme.txt:zone.identifier—— 这不是普通文件，不能用rename()重命名主体文件名 - PHP 8.0+ 对流封装器校验更严格，错误更早暴露；旧版本可能跳过校验但行为不可控
安全替换文件名的实操步骤（含冒号场景）
真正需要处理的，是用户上传或外部传入的、**本意是普通文件名但误含冒号**（如从 Windows 复制的字符串、OCR 识别错误、前端未过滤等）。此时应主动清洗，而非硬扛 :：
- 用
str_replace([':', '*', '?', '"', '', '|'], '_', $filename)批量替换 Windows 不合法字符（冒号只是其中之一） - 若需保留语义，可用
preg_replace('/[^a-zA-Z0-9._\- ]+/', '-', $filename)只留字母数字、点、下划线、短横和空格 - 务必在
move_uploaded_file()或rename()前完成清洗，且清洗后要trim()首尾空格、检查是否为空或只剩分隔符 - 不要依赖
basename()后直接使用——它不处理非法字符，只截路径
Windows ADS 文件（如 name.txt:stream）怎么处理
如果你确实遇到类似 report.pdf:Zone.Identifier 这种 ADS，它并非独立文件，而是主文件的扩展属性。PHP 无法通过常规文件函数读写 ADS 内容，也**不能用 rename() 改变其名称**：
立即学习“PHP免费学习笔记（深入）”；
- 删除 ADS：用 Windows 命令行执行
streams -d "report.pdf"（需 Sysinternals 工具），PHP 无法直接调用 - PHP 中检测是否存在 ADS：可尝试
file_exists('report.pdf:Zone.Identifier')，但返回false不代表不存在（权限或封装器限制） - 绕过 ADS 影响：始终以主文件名为操作目标（如
report.pdf），忽略冒号后部分；上传时用pathinfo($tmp_name, PATHINFO_FILENAME)提取基础名再清洗
function sanitize_filename(string $filename): string
{
$base = pathinfo($filename, PATHINFO_FILENAME);
$ext = pathinfo($filename, PATHINFO_EXTENSION);
// 移除所有 Windows 非法字符，替换为空格再压缩空格
$clean = preg_replace('/[\\\\/:*?"<>|]+/', ' ', $base);
$clean = preg_replace('/\s+/', '-', trim($clean));
// 确保不以点或短横开头/结尾，且不为空
$clean = trim($clean, '.-');
return $clean . ($ext ? '.' . $ext : '');
}
// 示例
echo sanitize_filename('my:file:name.txt'); // 输出：my-file-name.txt
echo sanitize_filename('photo?.jpg'); // 输出：photo.jpg
关键点在于：别试图让 PHP 和含冒号的文件名共存，先清洗再操作。Windows ADS 是系统级特性，PHP 层面能做的只有规避，不是对抗。
