Hugoplate (Hugo + Tailwind CSS) 建站全流程指南

1. 核心环境准备

Hugoplate 不同于基础 Hugo 主题，它强依赖于现代前端工具链：

• Hugo Extended 版本：必须安装支持 Sass/SCSS 的 Extended 版本，否则无法处理主题样式。
• Node.js (LTS)：由于主题使用 Tailwind CSS 编译，本地必须安装 Node.js。
• Git：用于版本管理和 Vercel 自动化部署。

2. 项目初始化与依赖安装

在本地解压或克隆主题后，第一步不是运行 Hugo，而是安装 Node 插件：

这个主题就是一个网站！只需要在主题中运行相关命令和修改就好！

1. 打开终端：进入项目根目录（如 E:\zhiwujie）。
2. 安装依赖：运行 npm install。这会安装 Tailwind CSS、PostCSS 等编译工具。
3. 启动预览：使用 hugo server。

3. 关键配置与避坑准则

A. 域名与路径 (hugo.toml)

• baseURL：必须设置为最终的线上地址（如 https://zhiwujie.xyz/），末尾带斜杠。
• 相对路径：建议设置 relativeURLs = true，这能极大减少部署后 CSS 丢失或链接跳回 localhost 的概率。

B. 配色修改 (data/theme.json)

• 不要修改 CSS 文件：Hugoplate 是数据驱动的，直接修改根目录下的 data/theme.json。
• 强制生效：修改配色后，如果本地没反应，需删除 resources/ 文件夹并重启 hugo server。

C. 多语言管理 (languages.toml)

• 目录匹配：contentDir 定义的文件夹（如 content/english）必须在磁盘上真实存在。
• 菜单关联：menus.en.toml 的文件名必须与语言代码（en）完全对应。

4. 部署逻辑（最重要的环节）

• 原则：推源码，不推 Public
  • 错误做法：只推送本地生成的 public 文件夹。这会导致所有链接锁死在本地地址。
  • 正确做法：将整个项目根目录推送到 GitHub（排除 public 和 resources）。
• Vercel 配置：
  • 框架预设：选择 Hugo。
  • 环境变量：如果需要强制覆盖域名，可在 Vercel 设置 HUGO_BASEURL 为你的域名。
• 清理构建：每次重大配置修改（如改域名、改配色）后，在 Vercel 部署时选择 “Redeploy with un-cached build”。

5. 常见错误速查表