WordPress插件添加本地图片最佳实践及代码修改咨询

1. 插件目录内图片的最佳实践 #

• 用官方函数生成URL：绝对不要硬编码图片路径，优先使用plugins_url()或plugin_dir_url()。这两个函数会自动适配WordPress的目录结构，不管插件放在哪个位置都能返回正确的URL。比如把你的../assets/images/改成plugin_dir_url(__FILE__) . 'assets/images/'，避免依赖文件层级的相对路径。
• 强制转义输出：所有HTML属性必须转义——src用esc_url()，alt用esc_attr()，这是防止XSS攻击的硬性要求，你的原代码已经做对了这一点。
• 按图片类型分情况处理：
  • 插件自带的静态资源（图标、固定配图）：直接用<img>标签配合官方路径函数即可，不需要加入媒体库。
  • 用户可上传/编辑的动态图片：必须用WordPress媒体库函数（比如wp_get_attachment_image()），这样能利用WP的图片尺寸生成、srcset自动适配等功能。
  • 优化图片性能：提前压缩静态图，或为不同设备准备多尺寸版本；如果是媒体库图片，利用WP的内置尺寸或自定义尺寸。

2. 消除NonEnqueuedImage警告的修改方案 #

插件检查工具的警告是建议使用WP官方图片处理函数，分两种场景处理：

场景一：需要将图片纳入媒体库（允许用户编辑替换） #

先在插件激活时把内置图片导入媒体库，之后用wp_get_attachment_image()调用：

1. 添加激活钩子导入图片：

register_activation_hook( __FILE__, 'my_plugin_import_static_images' );
function my_plugin_import_static_images() {
    $image_dir = plugin_dir_path( __FILE__ ) . 'assets/images/';
    $image_files = glob( $image_dir . '*.png' );

    foreach ( $image_files as $file ) {
        $filename = basename( $file );
        $filetype = wp_check_filetype( $filename );

        $attachment_args = array(
            'post_mime_type' => $filetype['type'],
            'post_title'     => sanitize_file_name( $filename ),
            'post_status'    => 'inherit'
        );

        // 插入到媒体库
        $attach_id = wp_insert_attachment( $attachment_args, $file );
        require_once ABSPATH . 'wp-admin/includes/image.php';
        $attach_meta = wp_generate_attachment_metadata( $attach_id, $file );
        wp_update_attachment_metadata( $attach_id, $attach_meta );

        // 存储附件ID到选项，方便后续调用
        update_option( 'my_plugin_img_' . str_replace( '.png', '', $filename ), $attach_id );
    }
}

2. 调用图片：

$attach_id = get_option( 'my_plugin_img_' . $key );
if ( $attach_id ) {
    echo wp_get_attachment_image( $attach_id, 'full', false, array( 'alt' => esc_attr( $label ) ) );
} else {
    // 降级到原方案，避免导入失败
    echo '<img src="' . esc_url( plugin_dir_url( __FILE__ ) . 'assets/images/' . $key . '.png' ) . '" alt="' . esc_attr( $label ) . '">';
}

场景二：图片是插件固定静态资源（无需用户编辑） #

不需要导入媒体库，用WP官方函数增强静态图片的输出即可，这样能通过插件检查：

function my_plugin_output_static_image( $img_key, $img_alt ) {
    $img_url = plugin_dir_url( __FILE__ ) . 'assets/images/' . $img_key . '.png';
    $img_path = plugin_dir_path( __FILE__ ) . 'assets/images/' . $img_key . '.png';

    // 获取图片尺寸
    $img_size = getimagesize( $img_path );
    $width = $img_size[0];
    $height = $img_size[1];

    // 生成响应式属性
    $attr = array(
        'alt' => esc_attr( $img_alt ),
        'width' => $width,
        'height' => $height,
    );
    $attr = wp_image_add_srcset_and_sizes( $attr, $img_url, $img_size );

    // 构建并返回img标签
    return sprintf( '<img src="%s" %s>', esc_url( $img_url ), wp_kses_hair( $attr, array() ) );
}

// 在需要显示图片的地方调用
echo my_plugin_output_static_image( $key, $label );

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