# Hugo + FixIt 本地开发速查


本文档区通过顶部菜单「文档」进入，每页左侧有页内目录（TOC）。下面是本机环境的速查命令。

## 环境版本

| 组件        | 版本                | 位置 / 说明                           |
| --------- | ----------------- | --------------------------------- |
| Hugo      | v0.169.0+extended | winget 用户级安装                      |
| FixIt     | v1.0.0-rc         | git submodule，锁定 commit `89a77ba` |
| Dart Sass | 1.108.1           | 官方独立二进制，位于用户 PATH 首位              |

## 常用命令

### 本地预览

```bash
hugo server -D
```

打开 `http://localhost:51888`，改动即时热更新。

### 生产构建

```bash
hugo --gc --minify
```

产物在 `public/`。构建前确认 `sass --version` 有输出，否则会报 `TOCSS-DART` 错误。

### 发布到 NAS

```powershell
.\deploy.ps1
```

脚本内部是 `hugo --gc --minify` + `robocopy .\public <NAS共享> /MIR`。

## 内容与资源约定

### 图片、附件

全部放全局 `static/`，正文用绝对路径：

```md
![示意图](/images/architecture.svg)
[下载清单](/files/deploy-checklist.txt)
```

### 独立 HTML

放 `static/html/`，构建后原样出现在 `/html/xxx.html`，不经 FixIt 渲染、不进本地搜索索引。因此要在 Markdown 里写「摘要 + 链接」把它引出来。

## 排错

### 构建报 taxonomy 错误

检查 `hugo.toml` 里是否有 `[taxonomies]` 且包含 `author = 'authors'`。

### 构建报 Sass 错误

确认 PATH 里第一个 `sass` 是官方独立版的 `sass.bat`，不是 npm 的 `sass.ps1` / `sass.cmd`。

### 菜单或 TOC 不生效

v1.0.0 用 `[[menus.main]]` 与 `[params.toc]`；旧版的 `menu.main`、`params.page.toc` 已失效。


---

> 作者: [Higer](https://higer.ren/)  
> URL: https://higer.ren/docs/hugo-fixit-local-dev/