React.js/Next.js中首次点击图片下载按钮下载.html文件异常

问题现象 #

在React.js-Next.js项目中，首次点击图片下载按钮时会下载当前页面的.html文件，后续点击则能正常下载目标图片。

复现代码 #

import Image from "next/image";
import { useState } from "react";
export default function Home() {
  const [downloadURL, setDownloadURL] = useState("");

  const download = async () => {
    const result = await fetch("http://localhost:3000/test.jpg", {
      method: "GET",
      headers: {},
    });
    const blob = await result.blob();
    const url = URL.createObjectURL(blob);
    setDownloadURL(url);
  };

  const handleDownload = async (e) => {
    try {
      await download();
      URL.revokeObjectURL(downloadURL);
    } catch (error) {
      console.error(error);
    }
  };
  return (
    <div className=" bg-gray-500 bg-opacity-75 transition-opacity flex flex-col justify-center  items-center">
      <Image src="/test.jpg" width={500} height={600} className="mb-2 " />
      <button
        onClick={handleDownload}
        type="button"
        className="flex-1 content-center text-center bg-indigo-600 py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
      >
        <a href={downloadURL} download="test">
          Download Image
        </a>
      </button>
    </div>
  );
}

问题原因 #

1. React状态异步更新：首次点击时，downloadURL初始为空字符串，<a href="">会默认触发当前页面的下载（即.html文件），而异步的download函数还未完成Blob URL的生成和状态更新。
2. 事件冲突+资源清理错误：按钮内嵌套<a>标签导致点击事件冲突；同时handleDownload中调用URL.revokeObjectURL(downloadURL)时，拿到的是状态更新前的旧值，无法正确释放内存，存在泄漏风险。

解决方案 #

方案一：直接创建临时链接触发下载（推荐） #

无需依赖状态存储Blob URL，在异步操作完成后直接生成临时标签触发下载，避免状态异步问题：

import Image from "next/image";

export default function Home() {
  const handleDownload = async () => {
    try {
      const result = await fetch("/test.jpg");
      const blob = await result.blob();
      const url = URL.createObjectURL(blob);
      
      // 创建临时a标签
      const tempLink = document.createElement("a");
      tempLink.href = url;
      tempLink.download = "test.jpg"; // 明确文件名后缀，确保文件类型正确
      document.body.appendChild(tempLink);
      tempLink.click();
      
      // 清理资源
      document.body.removeChild(tempLink);
      URL.revokeObjectURL(url);
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <div className="bg-gray-500 bg-opacity-75 transition-opacity flex flex-col justify-center items-center">
      <Image src="/test.jpg" width={500} height={600} className="mb-2" />
      <button
        onClick={handleDownload}
        type="button"
        className="flex-1 content-center text-center bg-indigo-600 py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
      >
        Download Image
      </button>
    </div>
  );
}

方案二：修复状态更新时机问题 #

若需保留状态方案，通过监听状态变化确保下载触发时机正确：

import Image from "next/image";
import { useState, useEffect } from "react";

export default function Home() {
  const [downloadURL, setDownloadURL] = useState("");

  const fetchImage = async () => {
    const result = await fetch("/test.jpg");
    const blob = await result.blob();
    const url = URL.createObjectURL(blob);
    setDownloadURL(url);
  };

  // 监听downloadURL变化，触发下载并清理资源
  useEffect(() => {
    if (downloadURL) {
      const tempLink = document.createElement("a");
      tempLink.href = downloadURL;
      tempLink.download = "test.jpg";
      tempLink.click();
      
      URL.revokeObjectURL(downloadURL);
      setDownloadURL(""); // 重置状态
    }
  }, [downloadURL]);

  return (
    <div className="bg-gray-500 bg-opacity-75 transition-opacity flex flex-col justify-center items-center">
      <Image src="/test.jpg" width={500} height={600} className="mb-2" />
      <button
        onClick={fetchImage}
        type="button"
        className="flex-1 content-center text-center bg-indigo-600 py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
      >
        Download Image
      </button>
    </div>
  );
}

关键注意事项 #

• 不要在按钮内嵌套<a>标签：避免按钮点击事件与<a>默认跳转事件冲突。
• 明确下载文件名后缀：确保浏览器能正确识别文件类型，避免下载后无法打开。
• 及时清理Blob URL：每次使用后调用URL.revokeObjectURL释放内存，防止内存泄漏。

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