本文详解如何通过 wpcf7_upload_file_name 钩子函数，在用户提交表单时自动重命名上传文件（保留原扩展名），适用于 WordPress 站点的文件安全与管理优化。
本文详解如何通过 `wpcf7_upload_file_name` 钩子函数，在用户提交表单时自动重命名上传文件（保留原扩展名），适用于 wordpress 站点的文件安全与管理优化。
Contact Form 7 默认会保留用户上传文件的原始名称，这可能带来安全风险（如恶意文件名）或管理混乱（如重复、含特殊字符的文件名）。幸运的是，CF7 提供了 wpcf7_upload_file_name 过滤钩子，允许开发者在文件保存前动态修改其名称——仅修改文件名部分，自动保留原始扩展名，无需手动解析或拼接后缀。
✅ 正确使用方式
该钩子接收两个参数：$filename（不含路径的原始文件名，如 resume.pdf）和 $args（包含表单字段、上传目录等上下文的数组）。需确保 add_filter() 的优先级和参数数量匹配（10, 2 表示默认优先级，接受 2 个参数）：
add_filter('wpcf7_upload_file_name', 'custom_cf7_rename_uploaded_file', 10, 2);
function custom_cf7_rename_uploaded_file($filename, $args) {
// ✅ 安全可靠：直接操作 $filename（已含扩展名），CF7 自动处理后续保存
$timestamp = date('Y-m-d_H-i-s_');
return $timestamp . $filename; // 示例：2024-05-20_14-30-22_resume.pdf
// 其他常用策略：
// return 'cf7-submission-' . uniqid() . '_' . basename($filename); // 唯一前缀 + 原名
// return sanitize_file_name('user-upload-' . time()) . '.' . pathinfo($filename, PATHINFO_EXTENSION); // 严格过滤 + 时间戳
}
⚠️ 关键注意事项
-
无需解析扩展名：
$filename已包含完整文件名（如photo.jpg），直接拼接前缀即可，CF7 内部会正确分离并验证扩展名； -
避免使用
$_FILES或路径操作：此钩子运行在 CF7 文件处理流程中，不应手动访问全局变量或尝试重写文件系统路径； -
命名需符合 WordPress 规范：建议使用
sanitize_file_name()包裹自定义部分（如前缀），防止非法字符导致保存失败； -
生效范围：该过滤器作用于所有 CF7 表单的文件上传字段，如需按表单或字段差异化处理，可检查
$args['name']（字段 name 属性）或$args['form_id']。
? 总结
通过 wpcf7_upload_file_name 钩子，你能在不修改 CF7 核心代码的前提下，实现上传文件的自动化、标准化重命名。推荐采用“时间戳+原文件名”或“唯一ID+原文件名”的组合策略，兼顾可追溯性与唯一性。将上述代码添加至主题的 functions.php 文件或专用插件中，即可立即生效。
