Hugo Docker 镜像

![Docker Pulls]([] ![Docker build]([]

镜像概述和主要用途

本镜像为 Hugo 静态网站生成器提供极简且功能完备的 Docker 镜像。镜像设计遵循"无魔法"原则：以服务器模式启动时自动设置 bind 参数，其他场景下保持原生 Hugo 行为。

核心功能和特性

• 极简设计：基于多种轻量级基础镜像（Busybox、Alpine、Debian、Ubuntu）构建，镜像体积小
• 版本齐全：提供 Hugo 官方版本及扩展版（ext 标签），满足不同功能需求
• 工具集成：部分镜像预安装 Asciidoctor、Pandoc 等文档处理工具
• CI/CD 优化：提供 ci 标签镜像，默认配置适合持续集成/部署环境
• 构建流程支持：onbuild 标签镜像简化静态网站构建流程
• 交互支持：Alpine/Debian/Ubuntu 系列镜像内置 Hugo Shell（bash + Hugo 自动补全）

使用场景和适用范围

• 静态网站本地开发与预览
• 静态网站自动化构建流程（CI/CD 集成）
• 包含复杂格式（AsciiDoc、Markdown 转换）的文档站点生成
• 需要 Hugo 扩展功能（如 PostCSS、NodeJS 支持）的项目
• 多环境一致性部署（开发、测试、生产）

镜像标签

Busybox 基础镜像

基于 Busybox 的极简镜像：

• 标签别名：latest、busybox、busybox-ci、ci、busybox-onbuild、onbuild
• 版本标签（Hugo 0.151.2）：0.151.2-busybox、0.151.2、0.151.2-busybox-ci、0.151.2-ci、0.151.2-busybox-onbuild、0.151.2-onbuild

Alpine 基础镜像

基于 Alpine 的极简镜像：

• 标准版标签别名：alpine、alpine-ci、alpine-onbuild
• 扩展版标签别名：ext-alpine、ext-alpine-ci、ext-alpine-onbuild
• 版本标签（Hugo 0.151.2）：0.151.2-alpine、0.151.2-alpine-ci、0.151.2-alpine-onbuild、0.151.2-ext-alpine、0.151.2-ext-alpine-ci、0.151.2-ext-alpine-onbuild

含 Asciidoctor 的 Alpine 镜像

基于 Alpine 并预安装 Asciidoctor 的镜像：

• 标签别名：asciidoctor、asciidoctor-ci、asciidoctor-onbuild、ext-asciidoctor、ext-asciidoctor-ci、ext-asciidoctor-onbuild
• 版本标签（Hugo 0.151.2）：0.151.2-asciidoctor、0.151.2-asciidoctor-onbuild、0.151.2-asciidoctor-ci、0.151.2-ext-asciidoctor、0.151.2-ext-asciidoctor-ci、0.151.2-ext-asciidoctor-onbuild

含 Pandoc 的 Alpine 镜像

基于 Alpine 并预安装 Pandoc 的镜像：

• 标签别名：pandoc、pandoc-ci、pandoc-onbuild、ext-pandoc、ext-pandoc-ci、ext-pandoc-onbuild
• 版本标签（Hugo 0.151.2）：0.151.2-pandoc、0.151.2-pandoc-ci、0.151.2-pandoc-onbuild、0.151.2-ext-pandoc、0.151.2-ext-pandoc-ci、0.151.2-ext-pandoc-onbuild

Debian 基础镜像

基于 Debian 的镜像：

• 标签别名：debian、debian-ci、debian-onbuild、ext、latest-ext、ext-debian、ext-debian-ci、ext-ci、ext-debian-onbuild、ext-onbuild
• 版本标签（Hugo 0.151.2）：0.151.2-debian、0.151.2-debian-ci、0.151.2-debian-onbuild、0.151.2-ext、0.151.2-ext-debian、0.151.2-ext-debian-ci、0.151.2-ext-ci、0.151.2-ext-debian-onbuild、0.151.2-ext-onbuild

Ubuntu 基础镜像

基于 Ubuntu 的镜像：

• 标签别名：ubuntu、ubuntu-ci、ubuntu-onbuild、ext-ubuntu、ext-ubuntu-ci、ext-ubuntu-onbuild
• 版本标签（Hugo 0.151.2）：0.151.2-ubuntu、0.151.2-ubuntu-ci、0.151.2-ubuntu-onbuild、0.151.2-ext-ubuntu、0.151.2-ext-ubuntu-ci、0.151.2-ext-ubuntu-onbuild

如需旧版本标签，请查看 完整标签列表。

使用方法和配置说明

命令行使用

常规构建

docker run --rm -it \
  -v $(pwd):/src \
  floryn90/hugo:0.151.2

运行开发服务器

docker run --rm -it \
  -v $(pwd):/src \
  -p 1313:1313 \
  floryn90/hugo:0.151.2 \
  server

Docker Compose 配置

常规构建

version: '3'
services:
  build:
    image: floryn90/hugo:0.151.2
    volumes:
      - ".:/src"

运行开发服务器

version: '3'
services:
  server:
    image: floryn90/hugo:0.151.2
    command: server
    volumes:
      - ".:/src"
    ports:
      - "1313:1313"

CI/CD 集成

GitHub Actions

在 .github/workflows/hugo.yml 中配置：

name: Hugo 构建

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 执行 Hugo 构建
        uses: floryn90/actions-hugo@1.0.0

更多配置详见 floryn90/actions-hugo。

Travis CI

在 .travis.yml 中配置：

language: bash
services:
  - docker
script:
  - docker run --rm -i \
      -v $(pwd):/src \
      floryn90/hugo:0.151.2

使用 bash 环境可加快 Travis 初始化速度。

Hugo Shell

Alpine/Debian/Ubuntu 系列镜像（含 Asciidoctor/Pandoc 版本）提供 Hugo Shell（bash + Hugo 自动补全）。进入项目 Shell：

docker run --rm -it \
  -v $(pwd):/src \
  floryn90/hugo:0.151.2-alpine \
  shell

Hugo 扩展版

名称含 ext 的镜像使用 Hugo 扩展版，提供额外工具支持。扩展功能支持情况如下表：

google/docsy 用户可使用 0.57.2 及以上版本的扩展镜像构建项目。

ONBUILD 镜像使用

onbuild 标签镜像会自动将 Dockerfile 所在目录内容复制到 /src 并构建到 /target（0.68.0 前为 /onbuild）。

示例：构建 Nginx 镜像（需 Docker 17.05-ce+）

# 构建阶段
FROM floryn90/hugo:0.151.2-onbuild AS hugo

# 部署阶段
FROM nginx
COPY --from=hugo /target /usr/share/nginx/html

构建参数

CI 镜像使用（0.77.0+）

ci 标签镜像专为持续集成/部署环境优化，与普通镜像的区别：

• 环境变量 HUGO_ENV 默认设为 production
• 入口点（entrypoint）为空，可直接执行命令

Pandoc 使用

含 Pandoc 的镜像支持 Hugo 外部格式转换。Hugo 默认通过 pandoc --mathjax 触发转换，可通过 HUGO_PANDOC 环境变量自定义参数：

docker run --rm -it \
  -v $(pwd):/src \
  -e HUGO_PANDOC="pandoc-default --strip-empty-paragraphs" \
  floryn90/hugo:0.151.2-pandoc

镜像中将原生 pandoc 重命名为 pandoc-default，通过 HUGO_PANDOC 定义的别名 pandoc 调用。

覆盖入口点

默认入口点为 hugo 包装脚本，如需直接使用原生 Hugo 可指定 hugo-official 入口点：

命令行

docker run --rm -it \
  -v $(pwd):/src \
  --entrypoint hugo-official \
  floryn90/hugo:0.151.2

Docker Compose

version: '3'
services:
  build:
    image: floryn90/hugo:0.151.2
    entrypoint: hugo-official
    volumes:
      - ".:/src"

版本信息

配置参数

环境变量

端口

• 1313/tcp：Hugo 开发服务器默认端口