Title: FirePunch | Instant AVIF & WebP images for ACF developers
Author: Matteo Bruschetti
Published: <strong>2026 年 7 月 2 日</strong>
Last modified: 2026 年 8 月 17 日

---

搜索插件

![](https://ps.w.org/firepunch-images-for-acf/assets/banner-772x250.png?rev=3595828)

![](https://ps.w.org/firepunch-images-for-acf/assets/icon.svg?rev=3595828)

# FirePunch | Instant AVIF & WebP images for ACF developers

 作者：[Matteo Bruschetti](https://profiles.wordpress.org/matteobruschetti/)

[下载](https://downloads.wordpress.org/plugin/firepunch-images-for-acf.2.2.5.zip)

 * [详情](https://cn.wordpress.org/plugins/firepunch-images-for-acf/#description)
 * [评价](https://cn.wordpress.org/plugins/firepunch-images-for-acf/#reviews)
 *  [安装](https://cn.wordpress.org/plugins/firepunch-images-for-acf/#installation)
 * [开发进展](https://cn.wordpress.org/plugins/firepunch-images-for-acf/#developers)

 [支持](https://wordpress.org/support/plugin/firepunch-images-for-acf/)

## 描述

**FirePunch** is a lightweight, 100% free plugin designed to optimize image management
in WordPress by automatically converting them into next-generation **AVIF** and **
WebP** formats.

This tool is built specifically for web developers working with custom themes and
image fields (such as **ACF – Advanced Custom Fields** or **Gutenberg blocks**).

### How does it work?

 1. **Automatic conversion:** The plugin intercepts JPG and PNG media uploads and generates
    variants asynchronously in the background, ensuring zero impact on server performance
    during your daily workflow.
 2. **Predictable URL Structure:** Converted AVIF and WebP variants are saved directly
    alongside the original media, making them instantly accessible by simply appending`.
    avif` or `.webp` to the original image URL. For example: `https://example.com/wp-
    content/uploads/immagine.jpg.webp` and `https://example.com/wp-content/uploads/
    immagine.jpg.avif`
 3. **Effortless Theme Integration:** Simply call them inside your custom theme using
    the standard WordPress function `wp_get_attachment_image()` or the plugin’s dedicated
    helper function `wp_avif_img()`.
 4. **Smart HTML5 Fallback:** The plugin automatically rewrites the frontend output
    into a robust `<picture>` tag. The browser will dynamically load the best possible
    format based on user compatibility, seamlessly prioritizing **AVIF**, falling back
    to **WebP**, and using the original **JPG** or **PNG** as the ultimate safety fallback.

### Key Features:

 * **Asynchronous Background Processing:** Leverages Action Scheduler (or WP-Cron
   with a safety offset) to process images sequentially without locking up the server
   or triggering execution timeouts. If a run is cut short by a server timeout anyway,
   it is detected and resumed automatically from where it stopped.
 * **Smart Hybrid Engine:** Tries ImageMagick first for premium encoding and seamlessly
   falls back to GD when necessary, dynamically boosting memory limits to prevent
   crashes on large files.
 * **Zero Disk I/O Abuse:** Caches the status of all available file variants directly
   inside the attachment metadata in the database. No endless file system lookups
   on every single page load.
 * **Modern HTML5 Rewriting:** Utilizes the native `WP_HTML_Tag_Processor` (introduced
   in WP 6.2) to safely rewrite `<img>` tags into multi-source `<picture>` structures.
 * **Automatic Cleanup:** When an image is deleted from the media library, all associated
   AVIF and WebP variants are permanently removed, featuring path traversal protection.
 * **Zero ACF Dependencies:** Built 100% WordPress-native with absolutely no reliance
   on Advanced Custom Fields, making it perfectly compatible with any custom theme
   workflow.

### Developer Guide (Custom Themes & ACF)

This plugin offers total flexibility for custom theme development. You can display
optimized images using three different approaches:

#### 1. Native Automatic Integration

If your theme already uses standard WordPress functions, you do not need to change
a single line of code. The plugin automatically filters the output and injects the
AVIF/WebP sources:

    ```
    <?php echo wp_get_attachment_image( $attachment_id, 'large' ); ?>
    ```

#### 2. Using the Helper Function firepunch_img()

If you need granular control—such as stripping away default WordPress layout classes
or easily overriding loading behavior—use the plugin’s global helper function:

    ```
    <?php echo firepunch_img( $attachment_id, $size, $attr ); ?>
    ```

Since version 2.2.5 the canonical name of this function is `firepunch_img()`. The
original name `wp_avif_img()` is still available and behaves identically, so no 
existing template needs to change: the `wp_` prefix is reserved for WordPress core,
and the new name avoids any future collision. Both names accept the same arguments.

 * **$attachment_id** (int): The attachment ID of the image (Required).
 * **$size** (string|array): The requested image size (‘thumbnail’, ‘medium’, ‘large’,‘
   full’). Default: ‘full’.
 * **$attr** (string|array): Simplifies attributes. You can pass ‘lazy’ or ‘eager’
   directly as a string, or supply a custom HTML attribute array.

Practical Examples:

    ```
    // Standard output in 'large' size with native lazy loading
    echo wp_avif_img( $image_id, 'large', 'lazy' );

    // Advanced output with custom CSS classes and specific Alt text
    echo wp_avif_img( $image_id, 'full', array(
        'class' => 'hero-banner-image',
        'alt'   => 'Optimized hero cover background'
    ) );
    ```

#### 3. Advanced Custom Fields (ACF) Integration

When creating an Image field in ACF, leave the **Return Format** to **Array**. This
approach allows you to dynamically extract the attachment ID for the optimization
engine while safely preserving a native standard HTML fallback. In your template
file, write:

    ```
    <figure>
       <?php if($acf_img_field): ?>
          <?php if ( function_exists('wp_avif_img') ) {
             $img_id = $acf_img_field['ID'];
             echo wp_avif_img($img_id, 'large', 'lazy');
          } else { ?>
             <img loading="lazy" src="<?php echo esc_url($acf_img_field['url']); ?>" alt="<?php echo esc_attr( $acf_img_field['alt'] ); ?>" />
          <?php } ?>
       <?php endif; ?>
    </figure>
    ```

## 安装

 1. Upload the plugin folder to the `/wp-content/plugins/` directory.
 2. Activate the plugin through the ‘Plugins’ menu in WordPress.

## 常见问题

### Is the plugin retroactive? Does it optimize existing media library images?

Yes. To avoid crashing your server’s CPU upon activation, the plugin does not run
a massive bulk-generation script. Instead, it optimizes older images dynamically“
on-the-fly” the first time a frontend user visits a page requesting them. Once generated,
the variant metadata is cached in the DB, eliminating future file system checks.

### How do I verify if images are being served in AVIF or WebP?

Visit your website’s frontend, right-click on an image, and select “Inspect” from
your browser developer tools. If you see your original tag wrapped inside a modern
block containing and tags, the plugin is working perfectly.

### What happens if my hosting server doesn’t support AVIF?

No crashes or errors will occur. The plugin performs environment capability checks.
If your server environment only supports WebP, it will generate WebP variants exclusively.
If the server libraries support neither next-gen format, it will perform a clean
fallback to the original JPEG/PNG files.

### Does it automatically process images added via the Gutenberg Block Editor?

Currently, this plugin focuses entirely on custom theme architecture, theme templates,
and custom meta fields (like ACF). It does not scan or overwrite the textual content
inside “the_content” block data, ensuring absolute structural speed and lightweight
database performance.

### Will I lose my converted image files if I deactivate the plugin?

No. Deactivating the plugin simply removes the frontend filters, returning your 
site to rendering the original JPEG/PNG files. All generated .webp and .avif files
remain completely secure within your “/uploads/” directory to avoid accidental data
loss, ready to be utilized again whenever you re-activate the plugin.

## 评价

此插件暂无评价。

## 贡献者及开发者

「FirePunch | Instant AVIF & WebP images for ACF developers」是开源软件。 以下人员
对此插件做出了贡献。

贡献者

 *   [ Matteo Bruschetti ](https://profiles.wordpress.org/matteobruschetti/)

[帮助将「FirePunch | Instant AVIF & WebP images for ACF developers」翻译成简体中文。](https://translate.wordpress.org/projects/wp-plugins/firepunch-images-for-acf)

### 对开发感兴趣吗?

您可以[浏览代码](https://plugins.trac.wordpress.org/browser/firepunch-images-for-acf/)，
查看[SVN仓库](https://plugins.svn.wordpress.org/firepunch-images-for-acf/)，或通过
[RSS](https://plugins.trac.wordpress.org/log/firepunch-images-for-acf/?limit=100&mode=stop_on_copy&format=rss)
订阅[开发日志](https://plugins.trac.wordpress.org/log/firepunch-images-for-acf/)。

## 更新日志

#### 2.2.5

Behavior changes worth knowing before you update:

 * GIF images are no longer converted. Imagick and GD write only the first frame
   into WebP and AVIF, so inside the picture tag the browser preferred a still image
   over the animated original and the animation was lost. The plugin has always 
   documented JPG and PNG as its scope, and now the code matches the documentation.
 * AVIF variants are generated at quality 60 instead of 82. The AVIF and JPEG quality
   scales are not comparable, and 82 sat well past the point where extra bytes stop
   buying visible quality. Expect noticeably lighter AVIF files. Use the new `firepunch_variant_quality`
   filter to change it.
 * A generated variant is now kept only when it is genuinely lighter than the source
   image. On small PNGs, logos, icons and tiny crops a next-gen variant can end 
   up larger than the original, and the browser would still have chosen it, downloading
   more bytes than doing nothing at all. Such variants are now discarded. This applies
   to newly generated files only: variants already sitting in your uploads folder
   are left untouched.
 * The picture tag is no longer injected in the WordPress admin, in REST API responses
   or in RSS feeds. It is only useful while the theme renders the page, and elsewhere
   it could break code that expects a single img tag.

Fixes:

 * Fixed a race condition that could permanently stop a newly uploaded image from
   ever receiving a picture tag. If a visitor loaded the image while the background
   conversion was still running, the frontend could write “no variants available”
   over the values the background job had just saved, and the result was never checked
   again.
 * Variants left behind by regenerating thumbnails, or by editing an image from 
   the WordPress editor (crop, rotate), are now removed instead of staying in the
   uploads folder forever, invisible to both the frontend and the media library.
 * Variants belonging to image edits stored in the attachment backup sizes are now
   deleted together with the attachment.
 * The metadata filter can no longer stay detached when a conversion fails. With
   Action Scheduler, which processes a whole batch in a single request, one failure
   used to disable the picture tag for every remaining image in that batch.
 * The uploads directory containment check is now case insensitive on Windows, where
   a mismatched drive or folder case could silently disable the entire plugin.
 * Uploads that are not images (archives, audio, video) no longer queue a background
   job that had nothing to do. PDF previews are still processed.
 * Conversions interrupted by a PHP timeout are now picked up and finished. On shared
   hosting a background run could be killed halfway through a large image, leaving
   some sizes without variants and nothing to restart them. The plugin now marks
   a run as started, and an hourly check re-queues anything that never reached the
   end, resuming from where it stopped. After three incomplete attempts an image
   is left alone instead of being retried forever. The scheduled check is removed
   when you deactivate the plugin.
 * Fixed the markup of the settings page: three section headings were closed with
   the wrong tag, and the verification steps list sat inside a paragraph, which 
   made the browser drop its intended styling.
 * Fixed the spacing of background jobs during bulk uploads. The queue spaces conversions
   ten seconds apart, but the value tracking the queue position expired after one
   hour, so any queue longer than an hour lost its place and every following job
   piled onto the same moment: exactly the burst the spacing exists to prevent. 
   The queue position now lives as long as the queue itself, and the queue can no
   longer be pushed more than six hours into the future, so the last images of a
   large import are not left waiting for days.

Performance:

 * The frontend no longer writes to the database while rendering the page. Detecting
   variants for older media used to run a database update per image inside the visitor’s
   response; those writes now happen after the response has been sent.
 * The memory limit is raised before the primary image library opens the file, instead
   of only inside the GD fallback, which is exactly where large PNG files were most
   likely to exhaust the available memory.
 * New `firepunch_variant_image_sizes` filter to restrict which registered image
   sizes get converted. A typical installation registers 12 to 18 sizes, which means
   up to about 38 encodings per upload, and most of them never end up in a picture
   tag. Restricting this list is also the most effective way to avoid timeouts on
   slower hosting.
 * The per-request cache used while detecting variants for older media is now capped,
   so a long running process such as `wp media regenerate` cannot grow it without
   limit.

Developer notes:

 * New global function `firepunch_img()`, the correctly prefixed canonical name.`
   wp_avif_img()` keeps working as an alias, so no template change is required.
 * Conversion failures are now written to the error log when WP_DEBUG is enabled,
   so “this server cannot produce AVIF” and “the conversion failed” are no longer
   indistinguishable.
 * The tutorial video on the settings page now loads from the privacy friendly youtube-
   nocookie.com domain, and only once it scrolls into view.
 * The plugin file now declares “Requires at least: 6.2”, matching what readme.txt
   has always stated, so WordPress warns you before installing on an older release
   instead of letting the picture tag silently stop working.
 * Removed a dead regular expression HTML parser. `WP_HTML_Tag_Processor` has been
   part of WordPress core since 6.2, the minimum version this plugin requires, so
   the fallback branch could never run: about 35 lines of hand written HTML parsing
   that carried maintenance and review cost for nothing.
 * Release hygiene: .DS_Store files are no longer shipped inside the plugin package,
   and the deploy workflow pins the release action to a fixed commit.

#### 2.2.4

 * Extended the path traversal protection to the variant generation routine, so 
   conversions are written only inside the uploads directory.
 * Newly registered image sizes are now detected on existing media instead of being
   permanently excluded from the picture tag.
 * Faster picture tag rendering: variant lookup for srcset candidates now uses an
   index instead of rescanning every registered image size for each candidate.

#### 2.2.3

 * Hardened the path traversal protection used during variant cleanup: the containment
   check no longer matches sibling directories sharing the uploads prefix, and is
   now separator and case normalized for Windows hosts.
 * Reduced database writes and disk I/O on the frontend: variant detection for legacy
   media is now cached per request and persisted only once per attachment, guarded
   against concurrent duplicate writes on servers with a persistent object cache.
 * Runtime-only metadata changes made by other plugins are no longer written permanently
   to the database when caching variant availability.
 * Replaced the temporary filter removal with a re-entrancy guard, so the metadata
   filter can no longer stay detached if a save fails mid-process.

#### 2.2.2

 * readme.txt fix

#### 2.2.1

 * readme.txt fix

#### 2.2

 * readme.txt YT video

#### 2.1

 * Added admin page to show current settings, plugin status and some debug information
   to diagnose issues.
 * Fixed blurry header banner on desktop screens.
 * Updated readme.txt documentation.

#### 1.2

 * Replaced the old regex parser with the native WP_HTML_Tag_Processor API for robust
   and safe HTML rewriting.
 * Resolved a potential PHP Warning in the file cleanup method caused by manually
   deleted upload subdirectories.
 * Optimized readme markup syntax for 100% compliance with the WordPress.org validator.

#### 1.1

 * Introduced the hybrid conversion workflow (Imagick + GD) featuring dynamic memory
   allocation adjustments for heavy PNG files.

#### 1.0

 * Initial plugin release.

## 额外信息

 *  版本 **2.2.5**
 *  最后更新：**2 月前**
 *  活跃安装数量 **不到10**
 *  WordPress 版本 ** 6.2 或更高版本 **
 *  已测试的最高版本为 **7.0.7**
 *  PHP 版本 ** 8.1 或更高版本 **
 *  语言
 * [English (US)](https://wordpress.org/plugins/firepunch-images-for-acf/)
 * 标签
 * [acf](https://cn.wordpress.org/plugins/tags/acf/)[AVIF](https://cn.wordpress.org/plugins/tags/avif/)
   [images](https://cn.wordpress.org/plugins/tags/images/)[performance](https://cn.wordpress.org/plugins/tags/performance/)
   [webp](https://cn.wordpress.org/plugins/tags/webp/)
 *  [高级视图](https://cn.wordpress.org/plugins/firepunch-images-for-acf/advanced/)

## 评级

尚未提交反馈。

[您的评价](https://wordpress.org/support/plugin/firepunch-images-for-acf/reviews/#new-post)

[查看全部评论](https://wordpress.org/support/plugin/firepunch-images-for-acf/reviews/)

## 贡献者

 *   [ Matteo Bruschetti ](https://profiles.wordpress.org/matteobruschetti/)

## 支持

有话要说吗？是否需要帮助？

 [查看支持论坛](https://wordpress.org/support/plugin/firepunch-images-for-acf/)