遇到的问题

部署延迟

这是本地经过 yarn deploy 后显示的情况，可见 Done in ...。但是真的部署成功了吗？

之后点击 https://eurekashadow.github.io/ 或者域名 https://www.eurekashadow.xin/,会出现下面这个页面：

这是可能是因为：GitHub Actions 使用的免费 CI/CD 资源（Runner）是共享的，在全球用户高峰期时出现了排队现象。打开Github 中的 Actions 可以看到正在排队状态，所以慢慢等吧。过一段时间，就会部署成功了：

经过后续使用发现，修复CNAME问题后，再也没有出现这种所谓的部署延时的问题，也许根本不是什么高峰期导致的，罪魁祸首可能是原来错误的 CNAME.txt！

关于CNAME

我看这篇文章的时候，ta说要在static目录下创建一个 CNAME.txt的空白文件。

现在我遇到的问题是，每次本地显示部署完成后Github端总是 自定义域名丢失 像这样：（之前我已经填过域名了）

问题分析

重新填写域名：

填写域名后会再次触发Github Actions：

这时候我打开Github仓库，查看 git-pages 分支，发现它又构建了一个 CNAME 文件（如下图，无文件格式），里面的内容是我的域名 www.eurekashadow.xin 我推测是在Github上重新添加 Custom domain 时自动构建了这个CNAME文件。那么之前提到的 CNAME.txt 是不是多余的呢？或者说实际上应该构建的是 CNAME 然后在里面加上域名 www.eurekashadow.xin 呢？

CANME 文件中内容：

CNAME问题结论

经测试发现，CNAME.txt 确实是 多余的 ！正确的做法：

创建无文件格式的CNAME

在新建的 CNAME 里面加入自己的域名：

之后就可以正常部署了：

yarn deploy

Github上的域名不会丢失：

高亮与行号冲突（未解决）

这是我的 docusaurus.config.js 配置：

docusaurus.config.js
prism: {
  // 代码高亮主题 - 浅色主题使用 GitHub 风格
  theme: prismThemes.github,
  // 代码高亮主题 - 深色主题使用 Dracula 风格
  darkTheme: prismThemes.dracula,
  
  // 自定义代码高亮标记配置
  magicComments: [
	// 高亮标记 - 用于突出显示重要代码行
	{
	  className: 'code-block-highlighted-line',  // CSS 类名
	  line: 'highlight-next-line',               // 行内标记
	  block: { start: 'highlight-start', end: 'highlight-end' }  // 块标记
	},
	// 新增代码标记 - 用于标识新增的代码行
	{
	  className: 'code-block-add-line',
	  line: 'highlight-add-line',
	  block: { start: 'highlight-add-start', end: 'highlight-add-end' }
	},
	// 更新代码标记 - 用于标识修改的代码行
	{
	  className: 'code-block-update-line',
	  line: 'highlight-update-line',
	  block: { start: 'highlight-update-start', end: 'highlight-update-end' }
	},
	// 错误代码标记 - 用于标识有问题的代码行
	{
	  className: 'code-block-error-line',
	  line: 'highlight-error-line',
	  block: { start: 'highlight-error-start', end: 'highlight-error-end' }
	},
  ],
  
  // 额外支持的语言（超出默认支持的语言列表）
  // 默认支持的语言列表参考：https://github.com/FormidableLabs/prism-react-renderer/blob/master/packages/generate-prism-languages/index.ts#L9-L23
  // Prism.js 完整支持语言列表：https://prismjs.com/#supported-languages
  additionalLanguages: [
	'java',   // Java 编程语言
	'json',   // JSON 数据格式
	'c',
  ],
},

这是关于 custom.css 配置：

custom.css
/* 代码高亮行的样式 */
.code-block-highlighted-line {
  background-color: rgba(255, 255, 0, 0.2); /* 黄色高亮 */
  display: block;
  margin: 0; /* 避免布局问题 */
  padding: 0 1em; /* 使用 em 单位更灵活 */
}

.code-block-add-line {
  background-color: rgba(0, 255, 0, 0.2); /* 绿色新增 */
  display: block;
  margin: 0;
  padding: 0 1em;
}

.code-block-update-line {
  background-color: rgba(0, 0, 255, 0.2); /* 蓝色更新 */
  display: block;
  margin: 0;
  padding: 0 1em;
}

.code-block-error-line {
  background-color: rgba(255, 0, 0, 0.2); /* 红色错误 */
  display: block;
  margin: 0;
  padding: 0 1em;
}

/* 深色主题下的样式 */
html[data-theme='dark'] .code-block-highlighted-line {
  background-color: rgba(255, 255, 0, 0.2);
}

html[data-theme='dark'] .code-block-add-line {
  background-color: rgba(0, 255, 0, 0.2);
}

html[data-theme='dark'] .code-block-update-line {
  background-color: rgba(0, 0, 255, 0.2);
}

html[data-theme='dark'] .code-block-error-line {
  background-color: rgba(255, 0, 0, 0.2);
}

这是高亮和行号同时使用的方法：

\```c showLineNumbers
#include <stdio.h>

int main() {
    //高亮下一行( highlight-next-line)
    printf("Hello, World!\n");
    
    //高亮开始( highlight-start)
    int x = 10;
    int y = 20;
    int sum = x + y;
    //高亮结束( highlight-end)
    
    return 0;
}
\```

这是显示冲突的情况：

高亮、行号可以单独使用，但两者同时使用就会造成冲突，别人都可以正常使用，为什么我就不行了？暂时未排查出原因！

暂时的妥协方法就是两者分开使用了。（20250919）

📦 node_modules 体积过大导致卡顿问题

🎯 问题现象

在本地开发环境中观察到明显的性能问题：

当 node_modules 文件夹体积过大时（如达到 17GB），本地运行的网站出现严重卡顿
页面间跳转缓慢，通常需要 3 秒以上才能完成导航
开发服务器编译时间显著增加
整体开发体验下降，影响工作效率

🔧 问题解决

通过清理 node_modules 文件夹解决此问题：

bash
npm install rimraf -g                           # 安装 rimraf 工具
rimraf node_modules                             # 删除 node_modules
npm cache clean --force                         # 清除缓存
# npm config set registry https://registry.npmmirror.com/  # 使用新淘宝镜像（可选）
npm install                                     # 重新安装依赖		

✨ 清理后的效果

node_modules 体积从 17GB 减少到约 200MB
项目编译速度显著提升
页面跳转几乎瞬间完成
本地开发环境运行流畅

💡 为什么清理是安全的

依赖声明机制
- 所有项目实际使用的依赖都明确记录在 package.json 文件中
- node_modules 只是这些声明依赖的"实例化"结果
- 重新安装时会根据 package.json 恢复所有必需依赖
npm/yarn 的设计原则
- 包管理器会确保 package.json 中声明的所有依赖都被正确安装
- 不会在重新安装时遗漏任何明确声明的依赖

📝 问题结论

node_modules 体积过大会显著影响本地开发环境性能，定期清理是保持开发环境高效运行的有效方法。此问题在大型项目中尤为明显，应作为常规维护工作来执行。

⚠️ 重要补充（后续观察）

经过进一步实践发现，开发环境卡顿可能有多个原因：

node_modules 体积问题（本小节主要讨论）
Docusaurus 构建缓存问题（可能更重要）

如果仅清理 node_modules 效果不明显，建议尝试清理 Docusaurus 构建缓存。

🚀 真正有效的解决方案

yarn
npx

yarn clear

npx docusaurus clear

这表明开发环境卡顿主要由 Docusaurus 构建缓存和开发服务器状态引起，而非 node_modules 体积问题。不过，定期清理不必要的依赖仍然很有必要，可以有效减少磁盘空间浪费。

build文件夹过大问题

这个问题排了好久好久，终于得以解决，吾心甚慰！~🥱

问题描述

build文件夹，或者更准确的说是其中的有6个js文件巨大，每个都有接近20mb左右，最终导致build文件夹总体达128mb。问了一下AI它说这是一种非常异常的情况，大型文件站的build文件夹都不一定能达到这个量级。

解决过程

于是我想方设法给build"瘦身"。一开始发现ForMDX.js文件中导入了没有用到的大型库，当时我几乎以为问题就要解决了，但是点击build属性一看还是128mb，给了我当头一击，我当时都要碎了。

现在已经半夜2点了，唉，今天的凡人还没看呢，老魔心魔不知道怎么呈现的。然后在AI的辅助下，一步步排查仍然没发现问题所在，后来灵机一动，把没用到的 src/components/FileBlock.tsx与src/theme/MDXComponents.tsx这两个文件删去，问题解决！build成功"瘦身"，变为13mb左右。

当前状态

现在是既没有喜悦也没用懊恼，只是无感，人麻了。关于此问题的进一步记录明天再来弄吧，睡觉先。

AI的问题总结

问题背景

现象：build 文件夹达到 128MB 的异常大小
解决后：删除两个未完成的文件后，build 文件夹降至 13MB 正常大小
问题根源：
- 保留src/components/FileBlock.tsx
- 保留src/theme/MDXComponents.tsx
- 但未完成 docusaurus.config.js 中 plugins 配置

问题成因分析

根本原因

循环依赖和错误导入
- FileBlock 组件中使用了 require('!!raw-loader!@site/' + filepath)
- 动态导入让 webpack 尝试处理项目中所有文件
MDX 组件循环引用
- MDXComponents.tsx 重新导出了 CodeBlock 组件
- 造成了组件映射的混乱
构建工具混乱
- webpack 无法正确解析依赖关系
- 大量不必要的文件被打包
- 生成错误的代码分割 chunks

问题解决过程

完整问题链

未完成的 FileBlock 组件 → 动态 raw-loader 导入 → webpack 尝试处理所有文件 → 
大量重复打包 → 错误的代码分割 → 生成巨型 JS 文件 → 128MB 构建文件

解决方法

删除两个干扰文件后，webpack 恢复正常工作：

消除动态导入源
恢复正常组件映射
清除构建工具困惑

经验教训

开发实践要点

未完成功能的潜在危害
- 即使未启用，残留代码也可能严重影响项目
- 及时清理未使用的代码文件
动态导入风险
- require('!!raw-loader!@site/' + filepath) 类动态路径需谨慎使用
- 会触发构建工具处理所有可能文件
组件覆盖注意事项
- 覆盖 Docusaurus 默认组件时要确保不破坏原有依赖关系

预防措施

及时清理未使用的代码文件
实验新功能时使用单独分支
定期检查自定义组件的依赖引入
注意主题组件的正确覆盖方式

后续建议

如需重新实现代码文件导入功能：

完成完整的插件配置，特别是 exclude 规则
限制文件访问范围，使用白名单机制
避免完全动态路径，使用更具体的路径模式

结论

13MB 的构建大小是正常的，说明问题已彻底解决。此案例说明在前端开发中，问题根源可能来自看似无关的残留文件，需要格外注意未完成功能的清理工作。

CardImg 组件点击图片卡死问题

原来关于图片组件的代码是放在，ForMDX.js 中的，后来迁出为 CardImg.js。

在 CardImg.js 中应该引入：

import { PhotoProvider, PhotoView } from 'react-photo-view';
import Lazyimg from 'react-lazyimg-component';
import 'react-photo-view/dist/react-photo-view.css';

实际上缺了：

import 'react-photo-view/dist/react-photo-view.css';

由于 ForMDX.js 中仍然保留那三条引入，故 CardImg.js 与 ForMDX.js 具有隐式依赖，此时图片组件正常工作。

但是由于后续在排查 build 文件夹过大问题的时候，发现 ForMDX.js 那三条引入是多余的，删去。此时隐式依赖断裂，图片组件无法工作。这种问题往往是很棘手的，虽然在本次问题中，再不济我也可以通过重构图片组件复现功能。但是如果在某种情况下这种重构变得尤为困难，甚至说简直不可能的时候，想要排查这种 隐式依赖 就会变得 极为困难！ 这次只是侥幸，记得图片组件似乎是要三个引入的，所以顺利将问题解决。日后应谨记此教训，在开发中，要尽量避免类似的错误。🥱

Vercel Preview 部署错误问题解决

问题描述

当使用 yarn deploy 部署到 GitHub Pages 的 gh-pages 分支时，Vercel 会自动检测到分支变化并尝试创建 Preview 部署，但由于 gh-pages 分支只包含静态文件而没有 package.json，导致构建失败，GitHub Deployments 中显示 ❌preview 错误。

问题原因

Vercel 默认会为所有分支推送创建 Preview 部署
gh-pages 分支是构建后的静态文件，缺少源代码和构建配置
Vercel 尝试运行 npm run build 失败

解决方案

配置生产环境构建：

进入 Vercel 项目 Settings → Git
在 Behavior 选项中选择 "Only build production"
确保生产分支设置为 main（或主分支）
保存设置

加载评论中...

部署延迟​

关于CNAME​

CNAME问题结论​

高亮与行号冲突（未解决）​

📦 node_modules 体积过大导致卡顿问题​

🎯 问题现象​

🔧 问题解决​

✨ 清理后的效果​

💡 为什么清理是安全的​

📝 问题结论​

⚠️ 重要补充（后续观察）​

🚀 真正有效的解决方案​

build文件夹过大问题​

问题描述​

解决过程​

当前状态​

问题背景​

问题成因分析​

根本原因​

问题解决过程​

完整问题链​

解决方法​

经验教训​

开发实践要点​

预防措施​

后续建议​

结论​

CardImg 组件点击图片卡死问题​

Vercel Preview 部署错误问题解决​

问题描述​

问题原因​

解决方案​

部署延迟

关于CNAME

CNAME问题结论

高亮与行号冲突（未解决）

📦 node_modules 体积过大导致卡顿问题

🎯 问题现象

🔧 问题解决

✨ 清理后的效果

💡 为什么清理是安全的

📝 问题结论

⚠️ 重要补充（后续观察）

🚀 真正有效的解决方案

build文件夹过大问题

问题描述

解决过程

当前状态

问题背景

问题成因分析

根本原因

问题解决过程

完整问题链

解决方法

经验教训

开发实践要点

预防措施

后续建议

结论

CardImg 组件点击图片卡死问题

Vercel Preview 部署错误问题解决

问题描述

问题原因

解决方案