如何在 VSCode 中配置运行并调试 Hexo 博客程序

在VSCode里跑Hexo时，很多人会遇到各种奇怪的问题——要么终端报错、页面空白，要么改完配置刷新一下，依旧是老样子。其实，绝大多数坑都集中在几个环节上。下面把这几个关键点掰开揉碎讲清楚。

VSCode 终端必须用 Git Bash，不能用 PowerShell 或 CMD

直接在 VSCode 里点终端→新建终端，默认启动的往往是 PowerShell。如果你在里头敲 hexo s，大概率会报错，或者页面一片空白，服务根本起不来。这可不是 Hexo 的锅，而是 Windows 下的 shell 环境出了问题——Hexo 内部依赖 Git 提供的Unix工具链（比如 sh），PowerShell 根本不支持这些。

解决办法有两个：

• 每次新建终端后，手动点右下角的 Shell 类型下拉框，切换到 Git Bash。
• 一劳永逸的方案：在 VSCode 设置里搜索 terminal.integrated.defaultProfile.windows，把它设为 Git Bash；或者直接在 settings.json 中加上一行："terminal.integrated.defaultProfile.windows": "Git Bash"。

这里有一个容易踩的坑：如果 Git 安装在非默认位置（比如 C:\PortableGit\bin\bash.exe），需要检查 terminal.integrated.profiles.windows 里对应 profile 的 path 值是否正确。路径不对，一切白搭。

启动服务前，工作目录和 clean 步骤一个都不能少

hexo s 启动失败或页面返回 404，90% 的原因只有两个：当前终端没有在 Hexo 项目的根目录，或者缓存没有清理干净。根目录的特征非常明显——必须包含 _config.yml、source/、themes/ 这样的文件和文件夹。

标准操作流程只有三步，缺一不可：

• 在 Git Bash 终端中 cd 到 Hexo 项目根目录，注意一定是根目录，不是子文件夹。
• 执行 hexo clean——这条命令不只是删除 public/ 目录，还会清除内存中的渲染缓存。
• 然后执行 hexo s（如果没有全局安装 hexo-cli，就用 npx hexo s）。

如果遇到 Cannot find module 'hexo-cli' 的错误，别急着重新全局安装。先检查项目根目录下的 package.json，看看 hexo-cli 是否在 devDependencies 里。如果存在，直接用 npx hexo s 更可靠。

改主题或配置后浏览器看不到变化？强制刷新 + 清缓存是硬性要求

编辑完 themes/xxx/layout/head.ejs 或 _config.yml 之后，即使重启 hexo s，浏览器显示的依然是旧样式。这既不是 bug，也不是 Hexo 的问题——它默认不会自动重建静态资源，浏览器也不会主动清除缓存。

必须同步做两件事：

• 保存文件后，在终端立即执行 hexo clean && hexo s（注意 && 的作用：只有 clean 成功，才会启动服务）。
• 浏览器访问 http://localhost:4000 时，按下 Ctrl + Shift + R 强制重载，绕过所有本地缓存。只点刷新按钮是没用的。

不要迷信“热重载”。Hexo 官方并不支持文件监听与自动重建，hexo-browsersync 这类插件在复杂主题（如 NexT、Butterfly）下极易引发冲突，甚至导致 hexo g 失败。最稳妥、最高效的方式，还是老老实实走 clean + s 的流程。

VSCode 里写 Markdown 文章，预览 ≠ 真实渲染

VSCode 自带的 Markdown 预览功能（Ctrl+K Ctrl+V）用起来确实顺手，但它只做纯语法解析，完全不会处理 Hexo 特有的内容：

• Front-matter 里的 title、date 等信息不会显示为文章头部。
• 模板变量如 {{ post.title }}、 会被原样输出，不会执行。
• 主题自定义标签（比如 {% youtube xxx %}）会直接当作普通文本显示。

所以，写完 source/_posts/my-post.md 之后，想看到博客的真实呈现效果，唯一的办法还是回到终端，执行 hexo clean && hexo s，然后用浏览器打开。VSCode 的 Markdown 预览只适合检查基础排版和链接格式，千万别把它当成最终效果。

Hexo 调试过程中，最容易出问题的往往是环境链路的某个断点：Git Bash → 正确的工作目录 → clean → 强制刷新。每一步都需要亲手确认，不能抱着“应该没问题”的心态跳过去。尤其是 hexo clean 这一步——很多人以为重启服务就够了，实际上如果不 clean，相当于拿着旧缓存跑新代码，结果肯定不会对。