VS Code Halo 插件完全使用指南：别再像我一样踩坑

如果你也在用 Halo 博客系统，并且希望通过 VS Code 来发布和管理文章，这篇文章就是为你准备的。我花了整整一下午踩坑，现在把这些经验整理出来，希望能帮你节省时间。

为什么需要这个插件？

Halo 后台的编辑器虽然够用，但对于习惯本地写作的人来说，还是不够爽：

本地 Markdown 编辑器（如 VS Code、Typora）写作体验更好
图片本地管理更方便
可以用 Git 做版本管理
写作时不依赖网络

VS Code Halo 插件就是为了解决这些问题而生——让你在本地写文章，一键发布到 Halo 博客。

一、安装和配置

1.1 安装插件

打开 VS Code
点击左侧扩展图标（或按 Ctrl+Shift+X）
搜索 Halo（作者：halo-dev）
点击安装

1.2 获取个人访问令牌

在 Halo 后台生成令牌：

登录 Halo 后台 → 点击右上角头像 → 个人中心
切换到 个人访问令牌 标签
点击 生成令牌，勾选 Post 相关权限（至少需要 manage 权限）
复制生成的令牌（注意：关闭弹窗后就看不到了，务必保存好）

1.3 初始化插件

在 VS Code 中按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows）
输入并选择 Halo: 初始化（或 Halo: Setup）
按提示填写：
- Halo 站点地址：你的博客地址，如 https://yourblog.com（不要带 /console，不要末尾斜杠）
- 个人访问令牌：上一步复制的令牌

二、核心概念：理解插件的工作方式

2.1 元数据的两种状态

首次发布前（只有顶层字段）：

---
title: 我的文章标题
slug: my-article-slug
categories:
  - 技术
tags:
  - Halo
  - VS Code
---

发布后（插件会自动添加 halo: 字段）：

---
title: 我的文章标题
slug: my-article-slug
categories:
  - 技术
tags:
  - Halo
  - VS Code
halo:
  site: https://yourblog.com
  name: 6023f047-3df5-4b04-9d39-d74bccc0cb1c  # 文章的 UUID
  publish: false  # 发布状态：false=草稿，true=已发布
---

2.2 最关键的理解（我踩过的坑）

字段位置	作用	说明
顶层 `title`, `slug` 等	文章基本信息	首次发布前必须写
顶层 `publish: true`	❌无效	不要在这里写
`halo.publish: true`	✅唯一有效	控制文章发布状态
`halo.name`	文章唯一标识	插件自动生成，不要手动修改

三、日常工作流程

3.1 首次发布新文章

在 VS Code 中新建 Markdown 文件，头部写元数据：
```
---
title: 我的新文章
slug: my-new-article
categories:
  - 教程
tags:
  - Halo
---
```
注意：此时不需要写 halo: 字段
编写文章内容，插入图片时使用本地路径：
```
![图片说明](./images/example.png)
```
按 Cmd+Shift+P → Halo: Publish
插件会自动：
- 上传所有本地图片到 Halo
- 创建文章
- 在文件头部自动添加 halo: 字段
- 文章默认状态为草稿（publish: false）
去 Halo 后台查看，确认文章已上传（此时是草稿状态）

3.2 发布文章（草稿→已发布）

在 Markdown 文件中，找到插件自动生成的 halo: 字段

将 publish: false 改为 publish: true：

halo:
  site: https://yourblog.com
  name: 6023f047-3df5-4b04-9d39-d74bccc0cb1c
  publish: true  # ✅ 改为 true

再次执行 Halo: Publish
文章就会在博客前台公开可见

3.3 更新已发布的文章

修改本地 Markdown 内容（文字、图片等）
确保 halo: 字段完整存在（特别是 name 不能丢）
如果只是更新内容，保持 publish: true 不变
执行 Halo: Publish
插件会：
- 根据 halo.name 找到对应的原文章
- 上传新增的本地图片
- 覆盖更新内容，保留阅读量、评论、发布时间

3.4 将已发布文章撤为草稿

将 halo.publish: true 改为 false
执行 Halo: Publish
文章在前台就会隐藏

四、常见问题（都是我踩过的）

Q1：执行 Publish 后一直显示“发布中”，卡住了怎么办？

可能原因：网络代理（VPN）导致响应超时。

解决方法：

关闭 VPN 或设置为直连
完全退出 VS Code（Cmd+Q）
重新打开，再次执行 Publish

如果还是卡住，可能是配置文件损坏：

# 删除插件配置文件（Mac/Linux）
rm ~/.config/preferences/run.halo.vscode.pref

# 重新执行 Halo: Setup 初始化

Q2：文章传到后台了，但是是草稿，怎么才能直接发布？

错误做法：在顶层写 publish: true ❌
正确做法：在 halo: 字段内写 publish: true ✅

halo:
  publish: true  # 这才是有效位置

Q3：我想用这个文件创建一篇全新的文章，但里面有 `halo:` 字段

解决方法：删除整个 halo: 字段（或暂时重命名），然后执行 Halo: Publish，插件会把它当作新文章处理。

Q4：更新文章时应该用哪个命令？

答案：还是用 Halo: Publish。插件会自动判断：

有 halo: 字段 → 更新已有文章
无 halo: 字段 → 创建新文章

插件里没有 Halo: Update 命令。

Q5：如何查看插件报错信息？

如果发布卡住但看不到错误：

Code → 设置 → 切换开发者工具
切换到 Console 面板
再次执行 Publish，看红色报错

五、注意事项总结

✅ 必须记住的规则

首次发布前：只写顶层字段（title, slug, categories, tags）
发布后：插件自动生成 halo: 字段，不要手动修改 name
控制发布状态：修改 halo.publish 的值（true=发布，false=草稿）
更新文章：始终用 Halo: Publish 命令
图片处理：本地图片会自动上传，直接用相对路径即可

❌ 常见错误

❌ 顶层写 publish: true
❌ 手动修改 halo.name
❌ 首次发布前预写 halo: 字段
❌ 在有 VPN 的情况下发布（容易卡住）

六、完整示例

首次发布前

---
title: VS Code Halo 插件使用指南
slug: vscode-halo-plugin-guide
date: 2026-03-01
categories:
  - 教程
tags:
  - Halo
  - VS Code
---

这里写文章内容...

![本地图片](./images/example.png)

发布后（插件自动添加）

---
title: VS Code Halo 插件使用指南
slug: vscode-halo-plugin-guide
date: 2026-03-01
categories:
  - 教程
tags:
  - Halo
  - VS Code
halo:
  site: https://yourblog.com
  name: 8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d
  publish: false
---

这里写文章内容...

![本地图片](./images/example.png)

发布到前台

halo:
  publish: true  # 改为 true 后执行 Publish

写在最后

这个插件本身是个好工具，但文档不够详细，元数据规则也比较特殊。希望这份指南能帮你少走弯路。

如果你在使用过程中遇到其他问题，欢迎留言交流。如果你发现本文有错误或遗漏，也请告诉我，我会及时更新。

本文就是使用 VS Code Halo 插件发布的（publish: true）

菜单