如何通过Gatsby+gatsby-remark-images实现Markdown图片高级样式？

我之前在搭建Gatsby博客时也遇到过完全一样的困扰——想用gatsby-remark-images的图片优化能力，又不想放弃Markdown的简洁性去写纯HTML。试了几个方案后，找到了几个靠谱的路子，分享给你：

方案1：用gatsby-remark-classes给图片加自定义类，配合CSS实现排版 #

这个方案最直接，核心是给Markdown里的图片标记添加自定义CSS类，让gatsby-remark-images处理后仍能带上这些类，再用CSS控制布局。

步骤： #

1. 先安装插件：

npm install gatsby-remark-classes --save-dev

2. 在gatsby-config.js里配置插件顺序（注意要放在gatsby-remark-images之前，因为remark插件是按顺序执行的）：

module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-classes`,
            options: {
              classMap: {
                image: 'img-container', // 默认给所有图片容器加基础类
              },
              // 支持从Markdown图片的标题里提取类，比如 ![图](img.jpg){.gallery-2}
              syntax: 'github',
            },
          },
          {
            resolve: `gatsby-remark-images`,
            options: {
              maxWidth: 1200,
              withWebp: true,
              loading: 'lazy',
              // 这里保留你原来的配置即可
            },
          },
        ],
      },
    },
  ],
};

3. 写CSS样式来实现不同排版：

/* 基础图片样式 */
.img-container {
  margin: 1.5rem 0;
}

/* 一行2张的画廊 */
.img-container.gallery-2 {
  width: 48%;
  display: inline-block;
  margin: 0 1% 1rem;
  vertical-align: top;
}

/* 一行3张的画廊 */
.img-container.gallery-3 {
  width: 31%;
  display: inline-block;
  margin: 0 1% 1rem;
  vertical-align: top;
}

/* 自定义宽度的单图 */
.img-container.w-75 {
  width: 75%;
  margin: 0 auto;
  display: block;
}

4. 在Markdown里这样用：

<!-- 一行2张的画廊 -->
![风景1](img1.jpg){.gallery-2}
![风景2](img2.jpg){.gallery-2}

<!-- 自定义宽度的单图 -->
![单张展示图](single.jpg){.w-75}

方案2：自定义Remark插件处理图片分组 #

如果需要更规整的画廊（比如自动把连续的图片分组），可以写一个简单的Remark插件，识别Markdown里的特定标记（比如:::gallery），把里面的图片包裹在一个容器里，再用CSS实现布局。

示例插件逻辑（可以放在项目的src/plugins/gatsby-remark-gallery/index.js）： #

const visit = require('unist-util-visit');

module.exports = ({ markdownAST }) => {
  let inGallery = false;
  let galleryNodes = [];

  visit(markdownAST, 'paragraph', (node, index, parent) => {
    const textNode = node.children[0];
    // 识别:::gallery开头和结尾的标记
    if (textNode && textNode.type === 'text') {
      if (textNode.value === ':::gallery') {
        inGallery = true;
        parent.children.splice(index, 1); // 移除标记
      } else if (textNode.value === ':::') {
        inGallery = false;
        // 创建包裹容器
        const galleryContainer = {
          type: 'html',
          value: '<div class="image-gallery">',
        };
        const galleryEnd = {
          type: 'html',
          value: '</div>',
        };
        // 把收集的图片节点插入到容器里
        parent.children.splice(index, 1, galleryEnd, ...galleryNodes, galleryContainer);
        galleryNodes = [];
      }
    } else if (inGallery && node.children.some(child => child.type === 'image')) {
      // 收集画廊里的图片节点
      galleryNodes.push(node);
      parent.children.splice(index, 1); // 从原位置移除
    }
  });

  return markdownAST;
};

然后在gatsby-config.js里添加这个自定义插件（放在gatsby-remark-images之前），再写CSS：

.image-gallery {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
  margin: 1.5rem 0;
}

.image-gallery .img-container {
  flex: 1 1 calc(33.333% - 0.666rem); /* 一行3张，自动适配 */
  margin: 0;
}

@media (max-width: 768px) {
  .image-gallery .img-container {
    flex: 1 1 calc(50% - 0.5rem); /* 移动端一行2张 */
  }
}

Markdown里这样用：

:::gallery
![图1](img1.jpg)
![图2](img2.jpg)
![图3](img3.jpg)
:::

方案3：在文章模板里通过GraphQL查询控制图片尺寸 #

如果需要更精细的尺寸控制（比如根据图片的文件名或alt文本设置不同尺寸），可以在博客文章的模板组件里，通过GraphQL查询获取图片的原始信息，然后在渲染时动态设置maxWidth。

比如在模板组件里：

import React from 'react';
import { graphql } from 'gatsby';

export default function BlogPost({ data }) {
  const post = data.markdownRemark;
  // 处理HTML里的图片，根据class调整样式
  const modifiedHtml = post.html.replace(
    /<div class="img-container(.*?)">/g,
    (match, className) => {
      if (className.includes('w-50')) {
        return `<div class="img-container w-50" style="max-width: 500px;">`;
      }
      return match;
    }
  );

  return (
    <div className="blog-post">
      <h1>{post.frontmatter.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: modifiedHtml }} />
    </div>
  );
}

export const query = graphql`
  query($slug: String!) {
    markdownRemark(fields: { slug: { eq: $slug } }) {
      html
      frontmatter {
        title
      }
    }
  }
`;

这个方案适合需要动态调整图片最大宽度的场景，配合前面的class方案一起用效果更好。

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