在 Docusaurus 中构建 QR Code 组件🐔

本文档记录了在 Docusaurus 项目中添加一个自定义二维码组件，并将其挂载到所有博客文章底部的完整流程。

---

1. 安装依赖

在项目根目录下安装二维码生成库：

npm install qrcode.react

2. 创建二维码组件

在 src/components/ 目录下新建 QrCode.js 文件：

import React from 'react';
import { QRCodeSVG } from 'qrcode.react';
import { useLocation } from '@docusaurus/router';

export default function QrCode({ url, size = 50 }) {
  const location = useLocation();

  // 只在博客详情页显示（路径匹配 /blog/xxx）
  const isBlogPost = /^\/blog\/[^/]+$/.test(location.pathname);
  if (!isBlogPost) return null;

  const targetUrl = url || (typeof window !== 'undefined' ? window.location.href : '');
  if (!targetUrl) return null;

  return (
    <div style={{ margin: '12px 0', textAlign: 'right' }}>
      <QRCodeSVG
        value={targetUrl}
        size={size}
        bgColor="transparent"
        fgColor="currentColor"
        level="H"
      />
      <p style={{ fontSize: '10px', color: 'var(--ifm-color-emphasis-600)', marginTop: '4px' }}>
        扫码阅读本文🐔
      </p>
    </div>
  );
}

3. 挂载到文章模板

在 src/theme/ 目录下新建 BlogPostItem.js 文件，用于覆盖默认的文章模板，将二维码组件附加到文章底部：

import React from 'react';
import OriginalBlogPostItem from '@theme-original/BlogPostItem';
import QrCode from '@site/src/components/QrCode';

export default function BlogPostItemWrapper(props) {
  return (
    <>
      <OriginalBlogPostItem {...props} />
      <QrCode />
    </>
  );
}

4. 样式说明

• 尺寸：size 默认设置为 50。40 在部分扫描器（尤其是 iOS 自带扫码）中可能无法识别，50 是一个更可靠的扫描下限。

• 背景：bgColor="transparent" 使二维码透明，适配亮色/暗色模式。

• 颜色：fgColor="currentColor" 使二维码颜色跟随当前文字颜色。

• 对齐：textAlign: 'right' 让二维码右对齐，类似印章效果。

• 提示文字：使用 Docusaurus 的 CSS 变量 var(--ifm-color-emphasis-600)，自动适配主题。

---

5. 可选：全局禁用二维码

如果需要在某些情况下暂时禁用二维码，可以将 QrCode.js 和 BlogPostItem.js 重命名为 .bkd 后缀，即可让 Docusaurus 忽略它们。

6. 清理与重启

修改完成后，建议重启开发服务器并清理缓存：

npm run start

如果遇到奇怪的报错，可以尝试：

npm run clear

---

7. 注意事项

• 二维码仅会在 /blog/xxx 详情页显示，不会出现在 /blog 列表页。

• 如果使用 Zen 浏览器开发时遇到缓存污染，可尝试切换至 Edge 或 Chrome 验证。

• 部署时，可通过 deploy.bat 脚本保护特定文件（如微信验证文件）不被覆盖。

---

8. 最终效果

二维码将出现在每篇博客文章的右下角，透明背景、右对齐、大小为 50px，并带有“神经肉鸡传播源”的文字提示。整体效果类似一枚数字印章。

---