os.Getenv
返回环境变量的值;若该环境变量未设置,则返回空字符串。
这一页解决什么问题
把构建环境里的信息带进模板:CI 流水线号、构建时间戳、部署的环境名(staging/production)。用环境变量而不是改配置文件,可以让同一份内容在本地与流水线上产出可区分的页面。
什么时候用,什么时候别用
该用:
- 从 CI/CD 注入的值(版本号、提交号、环境名);
- 需要「本地为空、线上有值」的行为。
别用:
- 站点自身可配置的参数 → 用
site.Params(写在hugo.toml里,可被使用者覆盖); - 读取文件内容 → 用
os.ReadFile; - 想取构建时间 → 用
time.Now。
用法
安全性
默认情况下,使用 os.Getenv 函数时 Hugo 允许访问:
CI环境变量- 任何以
HUGO_开头的环境变量
要访问其它环境变量,请调整项目配置。例如,允许访问 HOME 与 USER 环境变量:
toml
[security.funcs]
getenv = ['^HUGO_', '^CI$', '^USER$', '^HOME$']更多信息请参见配置安全性。
示例
go-html-template
{{ getenv "HOME" }} → /home/victor
{{ getenv "USER" }} → victor构建项目时可以传入值:
sh
MY_VAR1=foo MY_VAR2=bar hugo
OR
export MY_VAR1=foo
export MY_VAR2=bar
hugo然后在模板中取出这些值:
go-html-template
{{ getenv "MY_VAR1" }} → foo
{{ getenv "MY_VAR2" }} → bar完整示例(实测)
hugo.toml 使用默认安全配置;构建前设置环境变量 HUGO_ZH_TEST=hello-from-env(HUGO_ 前缀默认在白名单里)。
layouts/_partials/build-env.htmlgo-html-template
[{{ getenv "HUGO_ZH_TEST" }}]|[{{ getenv "HUGO_NOPE" }}]Hugo 0.167.0 实测输出:
[hello-from-env]|[]你应当看到什么:已设置的白名单变量取到值;HUGO_NOPE 虽在白名单里但没设置,返回空字符串(这是「未设置」的正常行为)。
配置 [security.funcs] getenv = ['^HUGO_', '^CI$', '^MY_TEST_VAR$'] 后,实测 {{ getenv "MY_TEST_VAR" }} 在设置该变量时返回其值,未设置时返回空字符串。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
变量在白名单内且已设置(实测 HUGO_ZH_TEST) |
变量值 | 否 |
变量在白名单内但未设置(实测 HUGO_NOPE、CI) |
""(空字符串) |
否 |
变量不在白名单(实测 HOME,默认配置) |
—— | 是,构建失败:error calling getenv: access denied: "HOME" is not whitelisted in policy "security.funcs.getenv"; the current security configuration is: |
在白名单里补上该变量(实测 [security.funcs] getenv=[…,'^MY_TEST_VAR$']) |
正常取到值 / 未设置时返回空串 | 否 |
| 返回类型 | string,永远不是 nil |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 报错看不懂 | access denied: "HOME" is not whitelisted in policy "security.funcs.getenv",整站构建失败 |
变量不在安全白名单里(实测默认只放行 CI 与 HUGO_*) |
在 [security.funcs] getenv 里加入对应正则,或换用 HUGO_ 前缀的变量名 |
| 没报错但结果不对 | 取到的值是空字符串 | 变量确实没设置,或名字拼写/大小写不一致 | 先用 with 判断非空再使用;核对变量名 |
| 没报错但结果不对 | 想改成站点参数却被使用者覆盖 | 用环境变量表达的是「构建环境」而不是「站点配置」 | 站点配置类参数改用 site.Params |
更多排查入口见故障排查。