本地预览

在你准备提交新 PR 之前,建议先预览你的变更。 预览可以帮助你发现构建错误或 Markdown 格式问题。

在本地预览变更

你可以选择构建网站的容器镜像,或者在本地运行 Hugo。构建容器镜像速度较慢,但可以显示 Hugo 短代码,这在调试时会很有帮助。

说明:

以下命令默认使用 Docker 作为容器引擎。你可以通过设置 CONTAINER_ENGINE 环境变量来覆盖此行为。

  1. 在本地构建容器镜像

    只有在你测试 Hugo 工具本身的变更时才需要这一步

    # 在终端中运行此命令(如果需要)
    make container-image
    
  1. 在本地仓库中获取子模块依赖:

    # 在终端中运行此命令
    make module-init
    
  1. 在容器中启动 Hugo:

    # 在终端中运行此命令
    make container-serve
    
  1. 在浏览器中访问 http://localhost:1313。Hugo 会监听文件变化,并在需要时重新构建网站。

  2. 要停止本地 Hugo 实例,返回终端并输入 Ctrl+C,或者关闭终端窗口。

或者,你也可以在本机安装并使用 hugo 命令:

  1. 安装 website/netlify.toml 中指定版本的 Hugo(Extended 版本)Node

  2. 安装相关依赖:

    npm ci
    
  1. 在终端中,进入 Kubernetes 网站仓库,并启动 Hugo 服务:

    cd <你的仓库路径>/website
    make serve
    

    如果你使用的是 Windows,或者无法运行 make 命令,可以使用以下命令:

    hugo server --buildFuture
    
  1. 在浏览器中,访问 http://localhost:1313。Hugo 会监听文件变化,并在需要时重新构建网站。

  2. 要停止本地 Hugo 实例,返回终端并输入 Ctrl+C,或者关闭终端窗口。

故障排查

错误:failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version

出于技术原因,Hugo 提供了两种二进制版本。当前网站仅支持 Hugo Extended 版本。 请在发布页面中查找名称包含 extended 的压缩包。 你也可以运行 hugo version,确认输出中包含 extended 字样。

macOS “打开文件过多”问题排查

如果你在 macOS 上运行 make serve 并遇到如下错误:

ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open files
make: *** [serve] Error 1

可以先检查当前的文件打开数量限制:

launchctl limit maxfiles

然后执行以下命令(参考 https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c):

#!/bin/sh

# These are the original gist links, linking to my gists now.
# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist
# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plist

curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist
curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist

sudo mv limit.maxfiles.plist /Library/LaunchDaemons
sudo mv limit.maxproc.plist /Library/LaunchDaemons

sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist

sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist

此方法适用于 Catalina 和 Mojave 版本的 macOS。

无法在本地找到镜像 'gcr.io/k8s-staging-sig-docs/k8s-website-hugo:VERSION'

如果你运行 make container-serve 时看到此错误,可能是因为你对 Makefile$IMAGE_VERSION 所定义的某些文件进行了本地修改(参见这里)。

网站镜像的版本号包含一个基于这些文件内容生成的哈希值。例如,如果这些文件的哈希为 1b9242684415, 则镜像名称为 k8s-website-hugo:v0.133.0-1b9242684415。 执行 make container-serve 时,会尝试从 Kubernetes 网站的 GCR 拉取对应镜像。 如果该镜像不是当前版本,就会出现“镜像不存在”的错误。

如果你需要修改这些文件并预览网站,则需要构建本地镜像,而不是拉取预构建镜像。你可以通过执行 make container-image 来完成。

其他问题 {other-issues}

如果你在本地运行网站或预览变更时遇到其他问题,欢迎在 GitHub 的 kubernetes/website 仓库中提交 Issue


最后修改 April 15, 2026 at 3:07 PM PST: [zh] Add preview-locally.md (bd4c2b65f3)