一、项目架构设计

1.1 目录结构规范

blog/
├── archetypes/           # 文章模板
│   └── default.md
├── assets/              # 需要处理的资源（SCSS, JS）
│   ├── css/
│   └── js/
├── content/             # 文章内容
│   └── posts/
├── data/                # 数据文件（JSON/YAML/TOML）
├── layouts/             # HTML 模板（覆盖主题）
│   ├── _default/        # 默认布局
│   ├── partials/        # 可复用组件
│   └── shortcodes/      # 短代码
├── static/              # 静态文件（直接复制）
│   ├── assets/
│   │   ├── css/
│   │   └── js/
│   └── images/
├── themes/              # 主题
│   └── PaperMod/
├── config.toml          # 站点配置
└── Makefile             # 构建脚本

1.2 配置分层架构

# hugo.toml - 核心配置
[params]
  # 功能开关
  enableWeather = true
  enableComments = false
  
  # 第三方服务
  [params.services]
    weatherAPI = "wttr.in"
    ipAPI = "ipapi.co"

二、CSS 调试技巧大全

2.1 浏览器开发者工具

快捷键：

  • Chrome: Cmd+Option+I (Mac) / Ctrl+Shift+I (Windows)
  • Safari: Cmd+Option+C（需开启开发菜单）

核心面板：

面板用途常用功能
Elements查看 DOM 和样式实时编辑 CSS，查看继承关系
ConsoleJavaScript 调试console.log(), 查看报错
Network网络请求监控检查 CSS/JS 是否加载
Sources源代码调试断点调试 JS

2.2 CSS 实时调试技巧

/* 1. 给元素添加彩色边框，查看边界 */
* {
  outline: 1px solid red !important;
}

/* 2. 查看特定元素 */
#weather-widget {
  outline: 2px solid blue !important;
  background: rgba(255, 0, 0, 0.1) !important;
}

/* 3. 检查盒模型 */
.weather-card {
  box-shadow: 0 0 0 1px red, 0 0 0 5px blue, 0 0 0 10px green;
}

2.3 响应式设计调试

/* 在浏览器控制台直接修改 */
/* 模拟手机 */
@media (max-width: 480px) {
  body::before {
    content: "Mobile View";
    position: fixed;
    top: 0;
    right: 0;
    background: red;
    color: white;
    padding: 5px;
    z-index: 9999;
  }
}

2.4 CSS 变量调试

// 在 Console 中查看 CSS 变量值
getComputedStyle(document.documentElement).getPropertyValue('--gap');
// "24px"

// 实时修改
document.documentElement.style.setProperty('--gap', '40px');

三、Hugo 构建高级技巧

3.1 本地开发服务器

# 基础命令
hugo server -D  # 包含草稿

# 高级选项
hugo server \
  --bind 0.0.0.0 \        # 允许局域网访问
  --port 1313 \           # 指定端口
  --buildDrafts \         # 构建草稿
  --buildFuture \         # 构建未来日期的文章
  --disableFastRender     # 禁用快速渲染（解决缓存问题）

3.2 构建优化

# 生产构建
hugo --minify --gc

# 选项说明
# --minify    压缩 HTML/CSS/JS
# --gc        清理缓存

3.3 模板调试

{{/* 在模板中打印变量 */}}
<pre>{{ printf "%#v" .Params | safeHTML }}</pre>

{{/* 检查变量是否存在 */}}
{{ if isset .Params "custom_field" }}
  {{ .Params.custom_field }}
{{ else }}
  {{ warnf "custom_field not found in %s" .Title }}
{{ end }}

四、组件开发最佳实践

4.1 天气组件架构（v3.3）

// 模块化设计
const WeatherApp = {
  // 配置层
  CONFIG: {},
  
  // 数据层
  API: {
    getWeather() {},
    getLocation() {}
  },
  
  // 存储层
  Cache: {
    get() {},
    set() {}
  },
  
  // 视图层
  UI: {
    render() {},
    renderLoading() {},
    renderError() {}
  },
  
  // 控制层
  init() {},
  loadWeather() {}
};

4.2 错误处理模式

async function safeFetch(url, options = {}) {
  try {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 5000);
    
    const response = await fetch(url, {
      ...options,
      signal: controller.signal
    });
    
    clearTimeout(timeoutId);
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.warn('Fetch failed:', error.message);
    return null; // 返回默认值
  }
}

五、Git 工作流

5.1 分支策略

# main 分支 - 生产环境
git checkout main

# 开发新功能
git checkout -b feature/weather-widget-v2

# 修复 bug
git checkout -b fix/css-responsive

# 合并到 main
git checkout main
git merge feature/weather-widget-v2
git push origin main

5.2 提交信息规范

# 格式: <type>(<scope>): <subject>

git commit -m "feat(weather): add IP-based city detection

- Use ipapi.co for Chinese city names
- Add fallback to browser geolocation
- Cache location for 10 minutes"

# Type 类型:
# feat: 新功能
# fix: 修复
# docs: 文档
# style: 格式（不影响代码运行）
# refactor: 重构
# test: 测试
# chore: 构建过程/辅助工具

5.3 自动化部署

#!/bin/bash
# deploy.sh

set -e

echo "🔨 Building..."
hugo --minify

echo "🧹 Removing old files..."
rm -rf public/

echo "📦 Copying new build..."
cp -r public/ ../

echo "🚀 Deploying to GitHub Pages..."
cd ../wubajie.github.io
git add .
git commit -m "deploy: $(date '+%Y-%m-%d %H:%M:%S')"
git push origin main

echo "✅ Done!"

六、性能优化

6.1 资源加载优化

<!-- CSS: 关键样式内联，非关键异步加载 -->
<style>
  /* 首屏关键 CSS */
  .weather-card { /* ... */ }
</style>
<link rel="preload" href="/css/non-critical.css" as="style" onload="this.onload=null;this.rel='stylesheet'">

<!-- JS: 异步加载，defer 执行 -->
<script src="/js/weather.js" defer></script>

6.2 缓存策略

// 智能缓存
const Cache = {
  get(key, ttl = 600000) { // 默认10分钟
    const item = localStorage.getItem(key);
    if (!item) return null;
    
    const { data, timestamp } = JSON.parse(item);
    if (Date.now() - timestamp > ttl) {
      localStorage.removeItem(key);
      return null;
    }
    return data;
  },
  
  set(key, data) {
    localStorage.setItem(key, JSON.stringify({
      data,
      timestamp: Date.now()
    }));
  }
};

七、调试清单

7.1 页面不显示检查清单

  • CSS 文件是否正确引用？
  • JS 文件是否正确引用？
  • DOM 元素是否存在？（document.getElementById）
  • 浏览器控制台有无报错？
  • 网络面板 CSS/JS 是否 200？

7.2 样式不一致检查清单

  • CSS 变量是否正确继承？
  • 父元素的 display 属性是什么？
  • 是否有其他样式覆盖？（Specificity）
  • 盒模型计算是否正确？（box-sizing）

7.3 构建失败检查清单

  • Hugo 版本是否兼容？
  • 模板语法是否正确？
  • Front matter 是否有效？
  • Git 子模块是否初始化？

八、扩展建议

8.1 未来功能

  1. PWA 支持: 离线访问、添加到桌面
  2. 暗色模式自动切换: 根据系统主题
  3. 文章阅读进度: 顶部进度条
  4. 代码复制按钮: 一键复制代码块
  5. 图片懒加载优化: Intersection Observer

8.2 监控与分析

// 简单访问统计（不依赖 Google Analytics）
const Analytics = {
  track(event, data) {
    const log = {
      event,
      data,
      url: location.href,
      timestamp: new Date().toISOString(),
      userAgent: navigator.userAgent
    };
    
    // 发送到自有后端或日志服务
    fetch('/api/analytics', {
      method: 'POST',
      body: JSON.stringify(log),
      keepalive: true
    }).catch(() => {});
  }
};

九、常用命令速查

# Hugo
hugo new posts/0018-new-post.md
hugo server -D
hugo --minify

# Git
git status
git add -A
git commit -m "message"
git push origin main
git log --oneline -10

# 调试
curl -s http://localhost:8080 | grep "weather-widget"
ls -la public/assets/

参考资源