Qwik 中本地图片为什么推荐用 ESM 导入

在 Qwik 项目里，如果我们直接这样写本地图片：

复制<img src="/imgs/head.webp" alt="头像" />

代码本身是可以运行的，但 ESLint 可能会提示 qwik/jsx-img。这个提示不是错误，而是 Qwik 在提醒我们：本地图片可以通过 ESM 导入的方式进行优化。

#问题来源

Qwik 推荐把本地图片放到 src 目录下，然后通过 import 导入，并在路径后面加上 ?jsx。

例如：

复制import ImgHead from '~/media/imgs/head.webp?jsx';

export default component$(() => {
  return <ImgHead alt="头像" />;
});

这样导入之后，图片会变成一个可以直接使用的组件。

#为什么要这样做

直接写 <img src="/xxx.webp" /> 时，浏览器只会加载这一张原图。图片多大，用户就下载多大。

而使用 Qwik 的 ?jsx 导入后，Qwik 会在构建阶段处理图片，例如：

• 自动压缩图片

• 自动生成不同尺寸的图片

• 自动生成 srcset

• 自动补充 width 和 height

• 默认使用懒加载 loading="lazy"

• 默认使用异步解码 decoding="async"

• 文件名会带 hash，方便长期缓存

这些优化对博客、官网、移动端页面都挺有用，尤其是头像、封面图、文章配图这种经常出现在页面上的图片。

#基本写法

普通写法：

复制import ImgHead from '~/media/imgs/head.webp?jsx';

export default component$(() => {
  return (
    <ImgHead
      alt="头像"
      class="h-24 w-24 rounded-full"
    />
  );
});

如果想指定图片尺寸，可以这样写：

复制import ImgHead from '~/media/imgs/head.webp?w=400&h=400&jsx';

注意：jsx 参数最好放在最后。

推荐：

复制import ImgHead from '~/media/imgs/head.webp?w=400&h=400&jsx';

不推荐：

复制import ImgHead from '~/media/imgs/head.webp?jsx&w=400&h=400';

#public 目录和 src 目录的区别

如果图片放在 public 目录下，一般会这样访问：

复制<img src="/imgs/head.webp" alt="头像" />

这种方式简单直接，适合：

• favicon

• robots.txt 相关资源

• 不需要优化的小图

• 第三方脚本需要固定路径访问的资源

• 一些背景图或静态下载资源

但它不会走 Qwik 的图片优化流程。

如果图片放在 src/media 或 src/assets 下面，就可以用：

复制import Image from '~/media/demo.webp?jsx';

这种方式适合：

• 头像

• 首页封面图

• 博客文章配图

• 产品图

• 需要控制加载性能的图片

#什么时候需要改

如果是页面里直接展示的图片，尤其是比较大的图片，建议改成 ?jsx 导入。

比如：

复制<img src="/imgs/about-bg.webp" alt="关于我背景" />

可以改成：

复制import AboutBg from '~/media/imgs/about-bg.webp?jsx';

<AboutBg alt="关于我背景" />

如果只是很小的图标，或者你本来就想保留固定路径，也可以不改。ESLint 提示只是性能建议，不是代码错误。

#我的使用建议

在 Qwik 博客项目里，可以简单按这个规则处理：

#总结

Qwik 的 qwik/jsx-img 提示，本质上是在提醒我们：本地图片不要只是当普通静态资源引用，也可以让构建工具帮我们做优化。

简单来说：

复制<img src="/imgs/head.webp" />

能用，但不会优化。

复制import ImgHead from '~/media/imgs/head.webp?jsx';

<ImgHead />

更适合 Qwik 项目，可以获得响应式图片、自动压缩、懒加载、宽高补全等优化。

所以在博客这种重视首屏速度和移动端体验的项目里，头像、封面、大图建议尽量使用 ?jsx 导入。