如何实现图片优先渲染，避免alt文本提前显示？

针对你在Docusaurus站点遇到的图片加载延迟导致alt文本先显示的问题，提供几个实用方案：

1. CSS + JS 控制图片显隐（通用方案） #

通过初始隐藏图片，加载完成后再显示，彻底避免alt文本闪现：

步骤1：添加全局CSS #

在你的Docusaurus项目的src/css/custom.css中加入：

img {
  opacity: 0;
  transition: opacity 0.3s ease;
  /* 可选：添加背景色占位，避免布局跳动 */
  background-color: #f5f5f5;
}

img.loaded {
  opacity: 1;
}

步骤2：添加加载监听脚本 #

在src/pages/_app.js（如果没有就新建）中加入：

import React, { useEffect } from 'react';
import App from '@docusaurus/app';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    const handleImageLoad = () => {
      document.querySelectorAll('img').forEach(img => {
        if (img.complete) {
          img.classList.add('loaded');
        } else {
          img.addEventListener('load', () => img.classList.add('loaded'));
          // 加载失败时显示alt文本
          img.addEventListener('error', () => img.style.opacity = 1);
        }
      });
    };

    handleImageLoad();
    // 监听路由切换，处理新加载的图片
    window.addEventListener('routeChangeComplete', handleImageLoad);
    return () => window.removeEventListener('routeChangeComplete', handleImageLoad);
  }, []);

  return <App Component={Component} pageProps={pageProps} />;
}

export default MyApp;

2. 使用Docusaurus官方Image组件（推荐） #

Docusaurus的内置Image组件支持模糊占位图，能替代alt文本的闪现，同时优化加载体验：

在MDX文件中使用 #

将Markdown格式的图片替换为JSX组件：

import Image from '@docusaurus/Image';

<Image
  src="/img/your-image.png"
  alt="你的图片描述"
  placeholder="blur"
  width={800}
  height={500}
/>

这个组件会自动生成图片的模糊缩略图作为占位，加载完成后平滑过渡到原图，完全不会显示alt文本。

3. 预加载首屏关键图片 #

如果首屏有核心图片，可通过预加载减少延迟：
在src/pages/_document.js的<head>中添加：

<link rel="preload" href="/img/hero-image.jpg" as="image">

这些方案都能解决你提到的问题，其中官方Image组件最适配Docusaurus生态，推荐优先使用。

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