使用Google Cloud Build构建Hugo静态站点Docker镜像后显示nginx默认页面的问题排查请求

我之前也碰到过类似Cloud Build+Docker多阶段构建的坑，咱们一步步来排查：

1. 镜像标签不匹配（最可能的元凶） #

你在Cloud Build构建时给镜像打了$BUILD_ID的专属标签，但push步骤里却没带上这个标签——这就导致你push到Registry的是默认的latest标签，而这个latest很可能是之前旧的镜像（里面根本没有正确生成的Hugo静态文件）。当你运行hugo-cloud时，Docker默认拉取latest标签，自然就显示nginx的默认页面了。

修复方法： #

修改Cloud Build配置，确保构建和push的标签完全对应：

steps:
  # 构建时同时打BUILD_ID和latest两个标签，方便后续使用
  - name: 'gcr.io/cloud-builders/docker'
    id: Build
    args:
      - 'build'
      - '-t'
      - 'eu.gcr.io/gcp-project/hugo-cloud:$BUILD_ID'
      - '-t'
      - 'eu.gcr.io/gcp-project/hugo-cloud:latest'
      - '.'
  # 一次性push所有标签（包括BUILD_ID和latest）
  - name: 'gcr.io/cloud-builders/docker'
    id: Push
    args:
      - 'push'
      - 'eu.gcr.io/gcp-project/hugo-cloud'

运行镜像时，要么指定刚构建的$BUILD_ID标签，要么确保latest是最新的版本：

# 用BUILD_ID标签运行，确保拉取的是刚构建的镜像
docker run -d -p 8080:80 eu.gcr.io/gcp-project/hugo-cloud:$BUILD_ID

2. Hugo构建阶段没生成静态文件 #

虽然Cloud Build显示构建成功，但环境和本地可能有差异，导致Hugo没正确生成文件：

子问题一：Git子模块没拉取 #

如果你的Hugo网站用了Git子模块（比如主题），Cloud Build默认克隆仓库时不会递归拉取子模块——你本地可能已经把主题下载好了，但Cloud Build的环境是全新的，缺少主题文件的话，Hugo根本生成不出完整的静态页面。

修复方法：在构建镜像前加一步拉取子模块：

steps:
  # 先拉取所有Git子模块，确保Hugo能找到主题
  - name: 'gcr.io/cloud-builders/git'
    id: PullSubmodules
    args: ['submodule', 'update', '--init', '--recursive']
  # 再执行构建和push
  - name: 'gcr.io/cloud-builders/docker'
    id: Build
    args:
      - 'build'
      - '-t'
      - 'eu.gcr.io/gcp-project/hugo-cloud:$BUILD_ID'
      - '-t'
      - 'eu.gcr.io/gcp-project/hugo-cloud:latest'
      - '.'
  - name: 'gcr.io/cloud-builders/docker'
    id: Push
    args:
      - 'push'
      - 'eu.gcr.io/gcp-project/hugo-cloud'

子问题二：Hugo构建输出为空 #

可以修改Dockerfile，加个命令查看Hugo生成的文件，方便在Cloud Build日志里验证：

FROM klakegg/hugo:0.104.3-onbuild AS hugo
# 查看/target目录内容，确认Hugo是否生成了静态文件
RUN ls -la /target
FROM nginx
COPY --from=hugo /target /usr/share/nginx/html

然后去Cloud Build的构建日志里看这个步骤的输出，如果/target目录是空的，说明Hugo构建有隐性错误，得进一步排查你的Hugo配置或内容问题。

3. Nginx配置的小概率问题 #

这个可能性很低，因为你本地运行正常，但如果前面的方法都没用，可以试试自定义Nginx配置，确保指向正确的静态文件目录：

FROM klakegg/hugo:0.104.3-onbuild AS hugo
FROM nginx
# 复制你自己的Nginx配置（如果有的话）
# COPY nginx.conf /etc/nginx/nginx.conf
COPY --from=hugo /target /usr/share/nginx/html

内容的提问来源于stack exchange，提问作者Stephan Michard