开始之前

​ 本页面描述了构建使用 Docsy 作为 Hugo 模块的站点。

安装 Hugo

​ 为了本地构建和预览使用 Docsy 的站点（比如这个示例站点），需要安 装最新的扩展版 Hugo（我们推荐使用版 本 0.73.0 或更高版本）。如果从发布页面进行安装，请确保获取的是支持 SCSS的扩展 版（extended） Hugo；你可能需要滚动到发布列表的末尾才能找到它。

​ 有关全面的 Hugo 文档，请参阅 gohugo.io。

在 Linux 上

​ 谨慎使用 sudo apt-get install hugo 命令进行安装，因为 它不能为所有 Debian/Ubuntu 版本提供扩展版 Hugo，也可能不是最新的版本。

​ 如果你已经安装了 Hugo，请检查其版本：

hugo version

​ 如果结果是 v0.109.0 或更早版本，或者看不到 Extended 字样，那么你需要安装最新 版本。在 Install Hugo 页 面中，可以查看完整的 Linux 安装选项。以下是从发布页面安装 Hugo 的方法：

1. 前往 Hugo releases 页面。

2. 在最新版本中，向下滚动直到找到扩展版 Hugo 的列表。

3. 下载最新的扩展版 Hugo（hugo_extended_0.1XX_Linux-64bit.tar.gz）。

4. 创建一个新目录：

   mkdir hugo
   

5. 将下载的文件解压到 hugo 目录中。

6. 切换到新的目录：

   cd hugo
   

7. 安装 Hugo：

   sudo install hugo /usr/bin
   

在 macOS 上

​ 使用 Brew安装 Hugo。

作为 npm 模块

​ 你可以使用 hugo-bin 将 Hugo 安装为 npm 模块。这将把hugo-bin添加到你的 node_modules 文件夹中，并将依赖项添加到 package.json 文件中。要安装 Hugo 的扩展版：

npm install hugo-extended --save-dev

​ 有关用法详细信息，请参阅hugo-bin 文档。

安装 Go 语言

​ Hugo 的模块管理命令需要在系统上安装 Go 编程语言。检查go是否已安装：

$ go version
go version go1.21.6

​ 确保您正在使用版本 1.12 或更高版本。

​ 如果go语言尚未安装在您的系统上，或者您需要升级它，请前往 Go 站点 的下载区域，选择适合您系统架构的安装程序并执行它。之后，检 查是否成功安装。

安装 Git VCS 客户端

​ Hugo 的模块管理命令需要在系统上安装git客户端。检查您的系统上是否已存 在git：

$ git version
git version 2.43.0

​ 如果您的系统上尚未安装git客户端，可以前往Git 站点， 下载适合您系统架构的安装程序并执行它。之后，检查是否成功安装。

安装 PostCSS

​ 要构建或更新站点的 CSS 资源，您还需要PostCSS来创建最终 的 assets。如果您需要安装它，则必须在您的计算机上安装最新版本的NodeJS，以便您可以使用npm，即 Node 包管理器。默认情况下，npm会在您运行npm install的目录下安装工具：

npm install -D autoprefixer
npm install -D postcss-cli

​ 从postcss-cli 的 8 版本开始，您还必须单独安装postcss：

npm install -D postcss

​ 请注意，如果全局安装 了PostCSS的版本大于 5.0.1，则不会加载autoprefixer，您必须使用本地安装。

安装/升级 Node.js

​ 为了确保您可以正确构建站点而不仅仅是执行hugo server，您必须安装最新的长期支持（LTS）版本的 Node.js。

如果您没有最新的 LTS 版本，则可能会看到以下错误之一：

Error: Error building site: POSTCSS: failed to transform "scss/main.css" (text/css): Unexpected identifier
#OR
/home/user/repos/my-new-site/themes/docsy/node_modules/hugo-extended/postinstall.js:1
import install from "./lib/install.js";
       ^^^^^^^

SyntaxError: Unexpected identifier
    at Module._compile (internal/modules/cjs/loader.js:723:23)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
    at Function.Module._load (internal/modules/cjs/loader.js:585:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)
    at startup (internal/bootstrap/node.js:283:19)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:623:3)

​ 您可以通过运行node -v来检查当前的 Node.js 版本。如果您需要安装新版本，请参阅 以下说明：

• 基于 Debian 和 Ubuntu 的发行版

  tl;dr:

  # Using Ubuntu
  curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
  sudo apt-get install -y nodejs
  
  # Using Debian, as root
  curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
  apt-get install -y nodejs
  

• 基于企业 Linux 的发行版

  tl;dr:

  # As root
  curl -fsSL https://rpm.nodesource.com/setup_18.x | bash -
  
  # No root privileges
  curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
  

接下来呢？

​ 在安装完所有必要的前提条件之后，选择如何开始你的新 Hugo 站点

• 从预设的站点开始（适合初学者）
• 从头开始创建站点（适合专家）