# .env.example（示例文件，提交到版本控制）
# 基础配置
HUGO_BASEURL=https://example.com
HUGO_ENVIRONMENT=production
HUGO_PARAMS_AUTHOR=Your Name
HUGO_PARAMS_EMAIL=[email protected]

# 第三方服务（请替换为实际值）
HUGO_PARAMS_GOOGLE_ANALYTICS=GA-XXXXXXXXX
HUGO_PARAMS_DISQUS_SHORTNAME=your-disqus-shortname

# 功能开关
HUGO_PARAMS_ENABLE_COMMENTS=true
HUGO_PARAMS_ENABLE_ANALYTICS=true

# .env.development（开发环境，不提交到版本控制）
HUGO_BASEURL=http://localhost:1313
HUGO_ENVIRONMENT=development
HUGO_BUILDDRAFTS=true
HUGO_BUILDFUTURE=true
HUGO_PARAMS_ENABLE_COMMENTS=false
HUGO_PARAMS_ENABLE_ANALYTICS=false

# .env.production（生产环境，不提交到版本控制）
HUGO_BASEURL=https://myblog.com
HUGO_ENVIRONMENT=production
HUGO_BUILDDRAFTS=false
HUGO_MINIFY=true
HUGO_PARAMS_ENABLE_COMMENTS=true
HUGO_PARAMS_ENABLE_ANALYTICS=true
HUGO_PARAMS_GOOGLE_ANALYTICS=GA-REAL-ID

#!/bin/bash
# scripts/load-env.sh

set -euo pipefail

ENV=${1:-development}
ENV_FILE=".env.${ENV}"

echo "加载 ${ENV} 环境配置..."

# 检查环境变量文件是否存在
if [[ ! -f "$ENV_FILE" ]]; then
    echo "警告: 环境变量文件 $ENV_FILE 不存在"
    echo "请基于 .env.example 创建该文件"
    exit 1
fi

# 加载环境变量
set -a
source "$ENV_FILE"
set +a

echo "环境变量已加载完成"

# 验证必需的环境变量
required_vars=(
    "HUGO_BASEURL"
    "HUGO_PARAMS_AUTHOR"
)

for var in "${required_vars[@]}"; do
    if [[ -z "${!var:-}" ]]; then
        echo "错误: 必需的环境变量 $var 未设置"
        exit 1
    fi
done

echo "环境变量验证通过"

# .env.secrets（敏感信息，绝不提交到版本控制）
HUGO_PARAMS_API_KEY="secret-api-key"
HUGO_PARAMS_DATABASE_URL="postgres://user:pass@host:port/db"
HUGO_PARAMS_OAUTH_CLIENT_SECRET="oauth-secret"

# .env.secrets.example（敏感信息模板）
# API 密钥
HUGO_PARAMS_API_KEY=your-api-key-here

# 数据库连接
HUGO_PARAMS_DATABASE_URL=postgres://user:pass@host:port/db

# OAuth 配置
HUGO_PARAMS_OAUTH_CLIENT_SECRET=your-oauth-secret

# config/_default/security.toml
[security]
# 执行安全配置
[security.exec]
allow = [
    '^dart-sass-embedded$',
    '^go$',
    '^npx$',
    '^postcss$'
]

# 环境变量白名单
[security.funcs]
getenv = [
    '^HUGO_',
    '^CI$'
]

# HTTP 请求限制
[security.http]
urls = [
    'https://api\.github\.com/.*',
    'https://.*\.googleapis\.com/.*'
]
methods = ['GET']

config/
├── _default/          # ✓ 基础配置
├── development/       # ✓ 开发环境配置
├── staging/          # ✓ 测试环境配置
└── production/       # ✓ 生产环境配置（不含敏感信息）

.env.example          # ✓ 环境变量示例
.env.secrets.example  # ✓ 敏感信息示例

.env.*               # ✗ 实际环境变量文件
.env.secrets         # ✗ 敏感信息文件
hugo.log            # ✗ 日志文件
public/             # ✗ 构建产物

#!/bin/bash
# scripts/validate-config.sh

set -euo pipefail

echo "验证 Hugo 配置..."

# 验证所有环境的配置
environments=("development" "staging" "production")

for env in "${environments[@]}"; do
    echo "验证 $env 环境配置..."
    
    if hugo config --environment "$env" > /dev/null 2>&1; then
        echo "✓ $env 环境配置有效"
    else
        echo "✗ $env 环境配置无效"
        exit 1
    fi
done

# 验证构建
echo "验证构建过程..."
if hugo --destination /tmp/hugo-validate-build > /dev/null 2>&1; then
    echo "✓ 构建成功"
    rm -rf /tmp/hugo-validate-build
else
    echo "✗ 构建失败"
    exit 1
fi

echo "配置验证完成！"

#!/bin/bash
# scripts/test-hugo.sh

set -euo pipefail

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# 测试函数
test_config() {
    local env=$1
    echo -e "${YELLOW}测试 $env 环境配置...${NC}"
    
    if hugo config --environment "$env" > /dev/null 2>&1; then
        echo -e "${GREEN}✓ $env 环境配置测试通过${NC}"
        return 0
    else
        echo -e "${RED}✗ $env 环境配置测试失败${NC}"
        return 1
    fi
}

test_build() {
    local env=$1
    echo -e "${YELLOW}测试 $env 环境构建...${NC}"
    
    local temp_dir="/tmp/hugo-test-$env-$$"
    
    if hugo --environment "$env" --destination "$temp_dir" > /dev/null 2>&1; then
        echo -e "${GREEN}✓ $env 环境构建测试通过${NC}"
        rm -rf "$temp_dir"
        return 0
    else
        echo -e "${RED}✗ $env 环境构建测试失败${NC}"
        rm -rf "$temp_dir"
        return 1
    fi
}

# 主测试流程
main() {
    echo "开始 Hugo 配置和构建测试..."
    
    local failed=0
    local environments=("development" "staging" "production")
    
    # 测试配置
    for env in "${environments[@]}"; do
        test_config "$env" || ((failed++))
    done
    
    # 测试构建
    for env in "${environments[@]}"; do
        test_build "$env" || ((failed++))
    done
    
    # 结果报告
    if [ $failed -eq 0 ]; then
        echo -e "${GREEN}所有测试通过！${NC}"
        exit 0
    else
        echo -e "${RED}$failed 个测试失败${NC}"
        exit 1
    fi
}

main "$@"

# Hugo 配置文档

## 环境配置

### 开发环境
- **环境变量文件**: `.env.development`
- **配置目录**: `config/development/`
- **特点**: 启用草稿、详细日志、禁用分析

### 生产环境
- **环境变量文件**: `.env.production`
- **配置目录**: `config/production/`
- **特点**: 启用压缩、分析、评论功能

## 重要配置说明

### 必需环境变量
- `HUGO_BASEURL`: 站点基础 URL
- `HUGO_PARAMS_AUTHOR`: 作者名称
- `HUGO_PARAMS_EMAIL`: 联系邮箱

### 可选环境变量
- `HUGO_PARAMS_GOOGLE_ANALYTICS`: Google Analytics ID
- `HUGO_PARAMS_DISQUS_SHORTNAME`: Disqus 短名称

## 部署配置

### S3 部署
需要设置以下 AWS 凭证：
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`

### CloudFront 配置
需要设置分发 ID：
- `CLOUDFRONT_DISTRIBUTION_ID`

## 故障排除

### 常见问题
1. **构建失败**: 检查环境变量是否正确设置
2. **样式异常**: 验证 PostCSS 配置
3. **部署失败**: 检查 AWS 凭证和权限

# config/_default/hugo.toml

# 站点基础配置
# baseURL 必须通过环境变量 HUGO_BASEURL 设置
baseURL = ""
languageCode = "zh-cn"
title = "我的技术博客"

# 构建配置
# 开发环境可以启用草稿构建
buildDrafts = false  # 由环境配置覆盖
buildFuture = false  # 不构建未来日期的文章
buildExpired = false # 不构建过期文章

# 性能配置
# 启用 Git 信息可以获取文章修改时间，但会影响构建速度
enableGitInfo = false  # 生产环境启用

# 分页配置
# 根据内容量调整每页文章数
paginate = 10
paginatePath = "page"

# 输出格式配置
# JSON 输出用于搜索功能
[outputs]
home = ["HTML", "RSS", "JSON"]  # 首页支持 JSON 搜索索引
page = ["HTML"]                 # 普通页面只输出 HTML
section = ["HTML", "RSS"]       # 章节页面支持 RSS 订阅

# Hugo 配置维护清单

## 月度检查
- [ ] 检查 Hugo 版本更新
- [ ] 验证所有环境配置
- [ ] 检查第三方服务配置有效性
- [ ] 审查环境变量安全性

## 季度检查
- [ ] 清理无用的配置项
- [ ] 更新文档和注释
- [ ] 检查部署性能
- [ ] 审查安全配置

## 年度检查
- [ ] 评估配置架构
- [ ] 更新最佳实践
- [ ] 培训团队成员
- [ ] 备份重要配置

#!/bin/bash
# scripts/monitor-config.sh

# 配置健康检查
check_config_health() {
    echo "检查配置健康状态..."
    
    # 检查配置文件语法
    if ! hugo config > /dev/null 2>&1; then
        echo "警告: 配置文件语法错误"
        return 1
    fi
    
    # 检查必需的环境变量
    local required_vars=("HUGO_BASEURL" "HUGO_PARAMS_AUTHOR")
    for var in "${required_vars[@]}"; do
        if [[ -z "${!var:-}" ]]; then
            echo "警告: 环境变量 $var 未设置"
            return 1
        fi
    done
    
    echo "配置健康检查通过"
    return 0
}

# 配置变更检测
detect_config_changes() {
    echo "检测配置变更..."
    
    if git diff --quiet config/; then
        echo "配置未发生变更"
    else
        echo "检测到配置变更:"
        git diff --name-only config/
    fi
}

# 主函数
main() {
    check_config_health
    detect_config_changes
}

main "$@"

# 配置变更流程

## 1. 提案阶段
- 创建变更提案文档
- 评估变更影响范围
- 获得团队审查批准

## 2. 实施阶段
- 在开发环境测试变更
- 更新相关文档
- 创建 Pull Request

## 3. 审查阶段
- 代码审查配置变更
- 运行自动化测试
- 部署到测试环境验证

## 4. 部署阶段
- 合并到主分支
- 部署到生产环境
- 监控变更效果

# Hugo 配置知识库

## 培训资源
- Hugo 配置原理讲解
- 实践操作演示
- 常见问题解答

## 联系方式
- 配置负责人：@config-owner
- 技术支持：@tech-support