👁 76 次阅读

如何消除 next/image 宽高比警告？

来源：https://github.com/vercel/next.js/issues/56025

现象描述

在 Next.js 项目中使用 next/image 的 <Image> 组件时，控制台会出现一条关于宽高比被修改的警告。issue 提交者给出的复现代码如下：

<Image
  className="cursor-pointer max-h-[32px] w-auto h-auto"
  src={"/23_store-dark.png"}
  alt="logo"
  width={300}
  height={32}
  priority
/>

提交者表示已经同时使用了 w-auto 与 h-auto，警告依旧出现，并尝试追加 Tailwind 类名后问题仍然存在。提交者给出的期望是控制台不再出现这条无法消除的警告。 issue 正文中用于搜索的警告原文为： > Image with src “/success-checkmark.gif” has either width or height modified, but not the other. If you use CSS to change the size of your image, also include the styles ‘width: “auto”‘ or ‘height: “auto”‘ to maintain the aspect ratio. 该 issue 的标签为 bug 与 Image (next/image)，截至最后一条评论日期 2026-08-06 仍处于 open 状态，官方尚未合入修复方案。剔除机器人或无效留言后，实质讨论共 61 条。

背景原因

要理解这条警告，需要区分三个不同的尺寸概念，issue 讨论中 markuslewin 在 2025-07-17 的评论给出了关键区分：

width 与 height 属性描述的是图片的固有尺寸（intrinsic / real size），即图片文件本身的像素尺寸。
CSS 中的 className 或 style 决定的是图片在页面上实际渲染的尺寸。
当 CSS 只改变了一个维度（例如限制了高度或宽度），另一个维度必须显式设为 auto，否则宽高比会被拉伸，浏览器与 Next.js 便无法保证比例一致。

terrymun 在 2023-09-26 的评论直接指出：同时把宽和高都设为 auto 并不合理，二者应当只保留其一为 auto。nicitaacom 在 2023-09-27 的回复补充了真实意图——希望图片保持 max-h-[32px] 的同时按原始宽高比显示，而不是被 width={300} 强行撑到 300px。因此警告的触发条件可以归纳为：

固有尺寸与实际渲染尺寸不一致；
CSS 只约束了其中一个维度；
另一个维度没有声明为 auto。

三者同时成立时，警告就会输出。仅凭 w-auto h-auto 而没有让固有尺寸与渲染尺寸形成一致关系时，警告依然会出现。

排查或量化方法

issue 讨论中贡献者采用过的定位方式，可以按以下顺序进行核对： 1. 确认图片文件本身的像素尺寸。markuslewin 在 2025-07-22 的评论中对某位用户上传的图片给出了明确判断：图片是 1855×535，这两个值就应当用于 width 与 height。这说明排查的第一步是把固有尺寸写对。 2. 确认 CSS 实际约束的是哪个维度。如果只限制了高度，宽度需要是 auto；反之亦然。 3. 借助浏览器开发者工具查看图片元素最终计算出的宽高，与固有尺寸做对比，判断是否存在单边被修改。 4. 注意 Tailwind Preflight 的默认行为。markuslewin 在 2025-07-22 的评论提到，Tailwind Preflight 已经设置了 height: auto，因此用 w-* 控制宽度往往是最直接的写法。 jananadiw 在 2026-08-06 的评论中记录了一次实测，用于区分警告是正确触发还是误报，其环境为：

next.js 14.2.35
tailwind css 3.2.4
macOS arm64
1280 x 720 viewport

其测试代码为：

<Image
  src="/logo.png"
  alt="Canvas Confetti"
  width={220}
  height={91}
  className="block h-[91px] w-[220px]"
/>

该评论描述图片的自然尺寸为 220 x 91，渲染尺寸与固有尺寸一致。这条实测说明只要两个维度都与固有尺寸对齐，警告不应出现；如果仍然出现，则属于需要单独上报的误报场景。

完整解决方案

issue 讨论中形成的可用写法并不唯一，社区给出的主流方案是：width 与 height 写图片的固有尺寸，再用 CSS 控制渲染尺寸，且只让一个维度为 auto。 markuslewin 在 2025-07-17 给出的完整示例：

export default function Home() {
  return (
    <div>
      <Image
        className="cursor-pointer max-h-[32px] w-auto"
        src={"/23_store-dark.png"}
        alt="logo"
        width={300}
        height={32}
      />
    </div>
  );
}

其要点是：width 与 height 保持不变，用于描述固有尺寸；CSS 中限制 max-h-[32px]，同时让宽度为 w-auto，从而使宽度随比例自动变化。 maktum827 在 2025-07-17 给出的方案是把 auto 写在 style 上：

<Image
  src={imageUrl}
  alt={name}
  width={40}
  height={40}
  style={{ width: "auto", height: "auto" }}
  priority
/>

cansuari 在 2025-07-23 的评论把这一方案称为「so far the best solution」，即同时使用 width/height 属性与 style 中的 width/height 属性，其给出的清晰示例为：

<Image src="/logo.svg" alt="alt text" width={120} height={32} style={{ width: '120px', hei

（该评论在 issue 页面上被截断，完整字符串未在讨论中给出，因此不补写。） DAShaikh10 在 2025-11-16 的评论也描述了自己的修复过程，给出的修改前后代码片段同样在页面上被截断，仅能看到 width={160}、height={40}、priority、className="rounded-tl-4xl mb-2" 等字段，无法据此还原完整写法。 Paget96 在 2023-09-26 给出的最早方案则要求在 style 中同时写死两个维度：

style={{ width: "300px", height: "32px" }}

或

style={{ width: "auto", height: "auto" }}

需要注意，terrymun 在同一天对「两个维度都为 auto」提出了质疑，认为这在语义上不成立。这一分歧在 issue 中并未被彻底消解。有用户按同一配置反馈仍不可用的情况也存在于讨论中：nicitaacom 在 2023-09-27 明确表示自己使用了 w-auto 与 h-auto 但问题依旧。

方案来源	核心写法	讨论中的评价
Paget96（2023-09-26）	`style={{ width: "300px", height: "32px" }}` 或 `style={{ width: "auto", height: "auto" }}`	被 terrymun 质疑两维 `auto` 不合理
markuslewin（2025-07-17）	固有尺寸写 `width`/`height`，CSS 用 `max-h-[32px] w-auto`	与 Tailwind Preflight 行为一致
maktum827（2025-07-17）	`style={{ width: "auto", height: "auto" }}`	与 Paget96 的第二种写法相同
cansuari（2025-07-23）	属性与 `style` 同时声明宽高	评论作者称其为目前最佳方案
markuslewin（2025-07-22）	图片 1855×535 时，属性写 `width={1855} height={535}`，用 `w-*` 控制渲染尺寸	针对具体图片的尺寸修正

常见错误排查

把 w-auto 与 h-auto 同时写上就以为万事大吉。terrymun 指出两维同时为 auto 不合理，nicitaacom 反馈该写法并未消除警告。
width/height 属性写成了期望的渲染尺寸，而非图片固有尺寸。markuslewin 在 2025-07-22 的评论明确要求把属性改为图片真实尺寸。
忽略了 Tailwind Preflight 已经设置 height: auto。重复设置会掩盖真正需要调整的维度。
只改了 CSS 却没有同步修正 width/height 属性，导致固有尺寸与渲染尺寸长期不匹配。
在渲染尺寸恰好等于固有尺寸时仍出现警告，这类情况属于需要单独上报的误报，不能靠调 CSS 消除。

实践建议

把 width/height 当作图片的元数据而非布局参数。布局全部交给 className 或 style。
只让一个维度承担比例推导职责。限制高度就设宽度为 auto，限制宽度就设高度为 auto。
处理真实项目中的图片时，先取到图片文件的真实像素尺寸，再决定属性值。markuslewin 对 1855×535 那张图的处理可作为参考。
若图片在渲染尺寸等于固有尺寸时依然报警，按实测记录环境与代码后单独上报，jananadiw 在 2026-08-06 的评论提供了一个可参考的记录模板（版本号、Tailwind 版本、平台、viewport 与图片代码）。
该 issue 仍为 open，官方尚未合入方案，上述写法均属社区在讨论中给出的结论，据 issue 讨论，不构成官方修复承诺。

FAQ

警告里说的「either width or height modified, but not the other」具体指什么？ 指 CSS 只改变了图片的一个维度，另一个维度没有设为 auto，导致宽高比可能被拉伸。markuslewin 的解释是：width 与 height 属性定义固有尺寸，CSS 定义渲染尺寸，若一个维度被 CSS 限制，另一个维度应当为 auto。 两个维度都写 auto 可以吗？ terrymun 在 2023-09-26 的评论认为这样不合理，二者只能取其一。nicitaacom 也反馈 w-auto 加 h-auto 未能消除警告。但 maktum827 与 cansuari 在 2025 年的评论中仍把 style={{ width: "auto", height: "auto" }} 作为有效写法推荐，说明社区内部对此存在分歧。 属性里的 width/height 到底该填什么？ 填图片文件的固有像素尺寸，而不是页面上想展示的尺寸。markuslewin 在 2025-07-22 的评论中直接以 1855×535 的图片为例，要求把这两个值写进属性。 Tailwind 项目里最省事的写法是什么？ 据 markuslewin 在 2025-07-22 的评论，Tailwind Preflight 已经设置了 height: auto，因此用 w-* 控制宽度通常最直接，无需再额外声明 h-auto。 这个 issue 官方修了吗？ 没有。该 issue 目前状态为 open，标签为 bug 与 Image (next/image)，最后一条评论日期为 2026-08-06，讨论中未出现维护者确认的修复版本或合并记录。