Hugo启动失败主因是工作目录错误或配置文件缺失：Hugo 0.128+默认生成hugo.toml而非config.toml，需确认cd进入站点根目录并检查文件名拼写及是否存在；Sublime Text仅作编辑器，构建依赖系统hugo二进制与正确working_dir设置。
hugo server 启动失败：找不到 config.toml 或 hugo.toml
Sublime Text 本身不参与 Hugo 构建流程，它只是编辑器；真正报错的是你在终端里执行的 hugo server。常见原因是当前工作目录不是 Hugo 站点根目录，或者配置文件名不匹配。
检查以下几点：
- 确认你 cd 进入的是包含
config.toml或hugo.toml的目录（即运行过hugo new site myblog后生成的那个顶层文件夹） - Hugo 0.128+ 默认生成
hugo.toml（TOML 格式），不是旧版的config.toml；如果手动改名或删了，hugo server会静默失败或提示 “no config file found” - 用
ls -a确认文件存在且拼写正确（注意大小写和扩展名） - 如果用了
--config参数但路径写错，也会失败；建议先不加参数直接运行
Sublime Text 中一键调用 hugo build / server 的配置方法
Sublime Text 可通过 Build System 实现快捷编译，但需注意：它调用的是系统 PATH 中的 hugo，不是内置引擎。
操作步骤：
- 在 Sublime Text 中，菜单栏选择 Tools → Build System → New Build System…
- 替换默认内容为以下 JSON（保存为
Hugo.sublime-build）：
{
"cmd": ["hugo", "server", "-D"],
"working_dir": "${project_path}",
"selector": "source.golang",
"variants":
[
{
"name": "Build",
"cmd": ["hugo"]
}
]
}
说明：
-
"working_dir": "${project_path}"是关键——它让命令在项目根目录执行，否则hugo找不到主题和内容 -
-D参数启用草稿（draft: true 的文章也能预览），开发时必备 - 保存后，在 Sublime 中按
Ctrl+B（Windows/Linux）或Cmd+B（macOS）即可启动服务 - 首次保存
.sublime-build文件时，Sublime 会自动将其放入Packages/User/目录，无需手动定位
content 下的 .md 文件不生成页面：draft 字段和文件路径问题
这是最常被忽略的“看不见的障碍”。Hugo 默认把新文章设为草稿，且对目录结构敏感。
排查清单：
- 打开你的
content/posts/my-post.md，确认 Front Matter 中没有draft: true；如有，删掉整行或改为draft: false - 确保文件放在正确的 section 目录下：
content/posts/对应postssection，content/about.md是单页（single page），而content/about/index.md是叶子节点页（leaf bundle） - 检查文件名是否含非法字符（如中文空格、全角标点），推荐只用英文、数字、短横线
- 运行
hugo list（Hugo 0.129+）可列出所有已识别的内容页，快速验证是否被加载
使用 extended 版本才能编译 SCSS / PostCSS 主题
很多流行主题（如 PaperMod、Stack、Hello-Friend）依赖 SCSS 编译。如果你用包管理器装的 Hugo（如 apt install hugo），大概率是 non-extended 版本，执行 hugo server 时会报错：
ERROR render of "page" failed: "/themes/PaperMod/layouts/partials/head.html:14:19": execute of template failed: template: partials/head.html:14:19: executing "partials/head.html" at <resources.scss>: error calling SCSS: this feature is not available in your current Hugo version</resources.scss>
解决办法只有换二进制：
- 去 GitHub Releases 下载
hugo_extended_*.tar.gz（Linux）或hugo_extended_*.zip（Windows） - 解压后替换你 PATH 中的
hugo二进制（如/usr/local/bin/hugo或C:\hugo\hugo.exe） - 运行
hugo version，输出中必须带extended字样才有效
非 extended 版本连 hugo server 都可能不报错，但 CSS 不生效——这种静默失败最难排查。
