如何使用wpcf7_upload_file_name修改Contact Form7上传文件名

wpcf7_upload_file_name是CF7官方提供的专门用于过滤上传文件名的过滤器，挂载自定义函数到这个钩子即可实现文件名修改，钩子一共支持3个传入参数：

• $filename：字符串，原始上传文件的完整名称（带扩展名）
• $file：数组，上传文件的临时属性，包含临时存储路径、原始文件名、错误码、文件大小等信息
• $args：数组，当前上传字段的配置项，包含字段名、允许上传的文件类型、大小限制等配置

基础实现代码 #

将以下代码添加到当前子主题的functions.php文件，或者你自己的自定义功能插件中即可生效：

add_filter('wpcf7_upload_file_name', 'customize_cf7_upload_filename', 10, 3);
function customize_cf7_upload_filename($filename, $file, $args) {
    // 提取原始文件的扩展名
    $file_extension = pathinfo($filename, PATHINFO_EXTENSION);

    // 自定义文件名主体部分，可按需修改规则
    // 示例规则：固定前缀+提交时间戳+3位随机数，避免重名
    $new_name_base = 'form_upload_' . date('YmdHis') . '_' . wp_rand(100, 999);

    // 拼接扩展名后返回新文件名
    return $new_name_base . '.' . $file_extension;
}

常见自定义场景 #

仅针对指定上传字段修改文件名 #

如果表单里有多个上传字段，只需要修改某一个字段的文件名，可以通过$args['name']判断字段名（字段名就是你在CF7表单编辑器里写[file 字段名]时设置的名称），示例：

add_filter('wpcf7_upload_file_name', 'customize_specific_cf7_file_name', 10, 3);
function customize_specific_cf7_file_name($filename, $file, $args) {
    // 仅对字段名为user-avatar的上传项生效，其他字段保持原名
    if ('user-avatar' !== $args['name']) {
        return $filename;
    }

    $file_extension = pathinfo($filename, PATHINFO_EXTENSION);
    
    // 示例：拼接用户提交的姓名+日期作为文件名
    $submission = WPCF7_Submission::get_instance();
    $new_name_base = 'avatar_anonymous';
    if ($submission) {
        $post_data = $submission->get_posted_data();
        // 假设表单里的姓名字段名为your-name，对输入做安全清洗
        $user_name = sanitize_title($post_data['your-name'] ?? 'anonymous');
        $new_name_base = 'avatar_' . $user_name . '_' . date('Ymd');
    }

    return $new_name_base . '.' . $file_extension;
}

注意：自定义文件名时不要直接使用未经过滤的用户输入，建议用sanitize_title()等WordPress内置函数做字符处理，避免出现特殊字符导致的文件存储失败、乱码问题；代码不要放在父主题的functions.php中，否则主题更新后代码会被覆盖。

内容的提问来源于stack exchange，提问作者Todra