编辑器
为常用编辑器提供 Hugo 语法支持的插件:怎么判断该不该装、VS Code 最小可用步骤、装完后的验证方法与常见故障。
开始之前,你需要
- 已经在用某个文本编辑器写 Hugo 站点(VS Code、JetBrains IDE、Emacs、Sublime Text、Vim 之一)。
- 知道站点根目录在哪,能打开
layouts/与content/里的文件。
读完之后你能
- 判断自己该装语法高亮/补全类插件,还是根本不需要插件;
- 在 VS Code 中完成一次最小安装,并验证高亮与补全确实生效;
- 看懂
Hugo Shortcodes之类插件的补全为什么有时不出现(它要扫描工作区里的模板); - 插件不工作时按「症状 → 真因 → 怎么修」表定位,而不是反复重装。
这一页解决什么问题
这一页回答一个很具体的问题:编辑器插件值不值得装,装哪个,装完怎么确认它真的在工作。
编辑器插件是本章代价最小的一类工具:它不碰你的内容文件,不改变构建流程,卸载即恢复原状。代价小也意味着收益有限——它主要解决三件事:
- 看得懂:
.html模板里的{{ … }}有没有高亮,直接决定你排查模板问题时眼睛累不累; - 少打字:短代码名称与参数、常用片段由补全给出,减少把
{{< … >}}拼错的机会; - 少翻页:主题开发时在多个文件之间跳转。
如果你只是偶尔改一改 content/ 下的 Markdown 正文,不装任何插件也能把站点建好——这是判断的起点。真正值得装的是「每天都在写 layouts/」的人。
该不该装:三类需求对照
| 你的主要工作 | 建议 | 对应插件 |
|---|---|---|
每天写 layouts/ 下的 Go 模板,经常被缩进和括号搞乱 |
值得装,优先格式化 + 高亮 | gotmplfmt、Hugo Language and Syntax Support |
| 文章里大量使用短代码,常写错参数名 | 值得装,优先补全 | Hugo Shortcodes |
| 主要工作是在主题的多个文件之间跳转 | 看编辑器,JetBrains 用户收益明显 | Smart Hugo、Hugo Themer |
| 只写 Markdown 正文,几乎不碰模板 | 可以不装 | ——(用编辑器自带的 Markdown 支持即可) |
| 维护多篇文章的日期、slug、SEO 字段 | 可以装,但注意它也会写前置元数据 | Front Matter |
一句话取舍:插件解决的是「写模板时的手感」,不是「站点能不能建起来」。所以任何插件装完发现不工作时,直接禁用就行,不要为它耽误建站进度。
最小可用步骤:VS Code + 语法支持
以最常见的组合为例。前置条件只有两个:装好 VS Code,以及用 VS Code 打开的是站点根目录(不是单个文件所在的文件夹)。
- 在 VS Code 中打开扩展面板(Windows/Linux 快捷键
Ctrl+Shift+X,macOSCmd+Shift+X)。 - 搜索
Hugo Language and Syntax Support,选中由budparr发布的那个,点击 Install。 - 打开站点根目录下任意一个模板文件,例如
layouts/_default/single.html;没有的话,先把主题目录里的同名文件复制一份过来(模板查找顺序里项目目录优先)。
你应当看到什么:文件被识别为 Go 模板(窗口右下角的语言模式显示 Go Template 一类的名称),{{ … }} 动作、{{ if }} / {{ end }} 关键字呈现与其他文本不同的颜色;输入 {{ 时能出现片段补全。如果颜色和普通 HTML 完全一样、右键也找不到「格式化文档」里的 Hugo 相关项,说明插件没装上或没生效——见文末常见坑。
可选:让格式化命令可用
gotmplfmt 扩展本身只是编辑器里的入口,格式化动作由外部命令行程序完成:装完扩展后,还需要系统里能调用 gotmplfmt CLI,否则触发格式化时会提示找不到命令。
go install github.com/gohugoio/gotmplfmt@latest这条命令要求本机有 Go 工具链;它会把可执行文件装到 $GOPATH/bin(默认 ~/go/bin,Windows 为 %USERPROFILE%\go\bin)。**实测:**在简体中文环境与国内网络下,go install 会从 proxy.golang.org 拉取模块,超时是常见现象,可先设置镜像源再重试:
go env -w GOPROXY=https://goproxy.cn,direct可选:短代码补全从哪来
Hugo Shortcodes 扩展的补全不是内置词表,而是扫描当前工作区里的模板来发现短代码名称与参数(上游原文:shortcode names and arguments discovered from workspace templates)。因此:
- 打开的是单个 Markdown 文件、而不是整个站点目录时,补全列表可能是空的;
- 站点里没有
layouts/_shortcodes/目录(例如短代码都由主题提供),补全能发现的内容也取决于主题是否在你的工作区内; - 自己新写的短代码模板,保存后重开文件或等待扩展重新扫描才会进入补全。
这三条解释了「为什么别人的补全很全,我这里什么都没有」——它通常不是装错了插件。
支持的编辑器与插件清单
Hugo 社区使用的编辑器相当分散,因此针对几款最流行的文本编辑器,都有人开发了插件,用来自动化工作流中的一部分环节。这些插件大多提供语法高亮、代码片段与补全,个别还会代为调用外部命令。下面按编辑器分组列出。各组清单之外,判断某个插件是否还值得装,看三处即可:市场页面的安装量、仓库最近一次提交、以及说明里是否写到与 Hugo 版本的关系。
Visual Studio Code
- gotmplfmt
- 由 Hugo 作者开发并维护,这个扩展借助 gotmplfmt 命令行工具格式化 templates(模板)。
- Front Matter
- 这个扩展用于维护文章的元数据,例如创建日期、修改日期、slug、标题、SEO 检查等。
- Hugo Helper
- 这个扩展提供了一些实用的命令。源码见其 GitHub 仓库。
- Hugo Language and Syntax Support
- 这个扩展提供语法高亮与代码片段。源码见其 GitHub 仓库。
- Hugo Shortcodes
- 这个扩展为 Markdown 中的短代码加上语法高亮与智能补全,短代码名称与参数会从工作区的模板中自动发现。源码见其 GitHub 仓库。
- Hugo Themer
- 这个扩展简化了主题开发,便于在主题的各文件之间跳转。
- Hugofy
- 这个扩展让项目开发更顺手。源码见其 GitHub 仓库。
- Syntax Highlighting for Hugo Shortcodes
- 这个扩展为 shortcodes(短代码)加上语法高亮,使各个片段在视觉上更容易辨认。
JetBrains IDEs
- Smart Hugo
- 这个插件适用于 IntelliJ IDEA、WebStorm、PhpStorm 等 JetBrains IDE,提供模板支持,包括语法高亮、动作补全、代码格式化,以及可选的高级功能。
Emacs
- emacs-easy-hugo
- 这个 Emacs 主模式支持用多种标记格式撰写博客,包括 Markdown、Org mode、AsciiDoc、reStructuredText、mmark 与 HTML。
- ox-hugo.el
- 这个原生 Org mode 导出器会导出带 front-matter(前置元数据)的 Blackfriday Markdown。它支持两种常见的 Org 博客工作流:把单个文件中的多棵 Org 子树导出为多篇文章,以及把单个 Org 文件导出为单篇文章。它还利用了 Org 的标签与属性继承特性。更多说明见 Why ox-hugo?。
Sublime Text
- Hugo Snippets
- 这个插件添加自动代码片段。
- Hugofy
- 这个插件让项目开发更顺手。
Vim
- Vim Hugo Helper
- 这个插件便于撰写页面与博客文章。
- vim-hugo
- 这个插件为模板提供语法高亮,以及另外几项功能。
常见坑
| 症状 | 真因 | 怎么修 |
|---|---|---|
装了插件但模板里 {{ … }} 没有任何颜色 |
当前文件没有被识别为 Go 模板(语言模式仍是 HTML),或打开的只是一个孤立文件目录 | 点击状态栏的语言模式手动切到 Go Template;改为「打开文件夹」打开站点根目录 |
| 格式化没反应,或提示找不到命令 | gotmplfmt 扩展需要外部 CLI,电脑上并没有这个程序 |
按上面的 go install 安装并确认 $GOPATH/bin 在 PATH 中;装好后重启编辑器 |
go install 长时间无输出后失败 |
国内网络访问 proxy.golang.org 超时 |
先 go env -w GOPROXY=https://goproxy.cn,direct,再重试;go env GOPROXY 可确认写入结果 |
| 短代码补全时有时无 | 补全内容来自工作区模板扫描,与打开方式、模板所在目录有关 | 用站点根目录作为工作区打开;确认站点或主题里有对应的短代码模板 |
| 扩展市场打不开、装不上 | 网络无法访问 marketplace.visualstudio.com(国内常见) |
到扩展的 GitHub 仓库发布页下载 .vsix,在扩展面板的「…」菜单里选择「从 VSIX 安装」 |
| 格式化后模板语法报错 | 配置或默认规则与项目约定不符,改动超出了预期范围 | git diff 查看被改动的文件,git checkout 回退,再按项目 README 调整配置 |
| 报错看不懂 | 报错来自插件,不是 Hugo 本身 | 执行 hugo --renderToMemory:退出码 0 说明站点自身没问题,可放心先禁用插件 |