2026-03-02 博客 hugo-teek +3 侧边栏配置博主卡片配置说明 1618 字 7 分钟 -- 次

博主卡片配置说明

最后更新于: 2026-03-02 04:47:45

👤 博主卡片概述

博主卡片是 Hugo-Teek 主题首页侧边栏的核心组件，始终显示在侧边栏最顶部（无开关控制）。它展示博主的个人信息、头像、状态表情和社交链接，是站点的【个人名片】。

✨ 卡片特性

🎨 设计特性

圆形旋转头像：支持多种形状和动画效果
动态背景：可设置个性化背景图片
状态表情：右下角显示当前状态图标
社交链接：支持多个社交平台链接

⚙️ 功能特性

响应式布局：自适应不同屏幕尺寸
懒加载优化：头像和背景图片按需加载
外链跳转：社交链接支持新窗口打开
图标支持：内置多种社交图标

📁 配置文件路径

博主卡片配置位于主题专属配置文件中：

主题配置文件📄 配置章节定位📝

1# hugo-teek-site/config/themes/hugo-teek/params.toml
2# 博主卡片配置位于 [blogger] 章节

1# ========================================
2# 博主卡片 (Blogger Card)
3# ========================================
4[blogger]
5    # 博主卡片所有配置项...

📝 基础配置项

头像配置

博主头像支持多种形状和样式：

头像基础配置📝 配置说明📝

1    avatar = "https://img.xxdevops.cn/blog/avatar/yuwen_avatar.avif?w=150&h=150&fit=crop&fm=webp&q=80"
2    name = "余温Gueen"
3    slogan = "明心静性，爱自己"

1    avatar = "图片URL"     # ◀️ 头像图片地址，建议使用 CDN
2    name = "博主名称"       # ◀️ 显示名称
3    slogan = "个性签名"     # ◀️ 个性签名/标语

头像形状配置

通过 shape 字段设置头像形状：

头像形状配置🎨 可选形状值🎨

1    shape = "circle-rotate"   # ◀️ 圆形旋转效果

1    shape = "circle"          # ◀️ 普通圆形
2    shape = "circle-rotate"   # ◀️ 圆形带旋转动画
3    shape = "square"          # ◀️ 正方形
4    shape = "rounded"         # ◀️ 圆角矩形

🖼️ 背景图片配置

卡片背景

博主卡片支持设置个性化背景图片：

背景图片配置🖼️ 背景配置说明📝

1    backgroundImage = "https://img.xxdevops.cn/blog/wallpaper/bg14.avif"

1    # ◀️ 背景图片 URL，留空则使用纯色背景
2    backgroundImage = "https://example.com/bg.jpg"
3    
4    # ◀️ 不设置或设置为空字符串使用默认纯色背景
5    backgroundImage = ""

圆形背景图（装饰效果）

圆形背景配置⭕ 圆形背景说明📝

1    circleBgImg = "https://img.xxdevops.cn/blog/avatar/yuwen_avatar.avif?w=300&h=300&fit=crop&fm=webp&q=80"
2    circleBgMask = false

1    # ◀️ 圆形装饰背景图，通常使用放大版头像
2    circleBgImg = "图片URL"
3    
4    # ◀️ 是否启用遮罩效果，true 时添加渐变遮罩
5    circleBgMask = false

😊 状态表情配置

右下角状态图标

博主卡片右下角可以显示状态表情图标：

状态表情配置😊 常用状态示例😊

1    icon = "😪"           # ◀️ 状态表情符号
2    size = 18.0           # ◀️ 图标大小（像素）
3    title = "困"          # ◀️ 鼠标悬停提示文字

 1    icon = "😊"           # ◀️ 开心
 2    title = "心情不错"
 3
 4[blogger.status]
 5    icon = "💻"           # ◀️ 工作中
 6    title = "正在coding"
 7
 8[blogger.status]
 9    icon = "☕"           # ◀️ 休息中
10    title = "喝咖啡中"
11
12[blogger.status]
13    icon = "🎮"           # ◀️ 游戏中
14    title = "正在游戏"

🔗 社交链接配置

添加社交链接

社交链接显示在博主名称下方、个性签名上方：

社交链接配置🔗 配置字段说明📝

 1# GitHub
 2[[blogger.social]]
 3    name = "GitHub"
 4    icon = "github"
 5    url = "https://github.com/JSXGQ"
 6
 7# CNB
 8[[blogger.social]]
 9    name = "CNB"
10    icon = "cnb"
11    url = "https://cnb.cool/u/yuwenGueen"
12
13# QQ
14[[blogger.social]]
15    name = "QQ"
16    icon = "qq"
17    url = "tencent://message/?uin=你的QQ号"
18
19# 微信
20[[blogger.social]]
21    name = "微信"
22    icon = "weichat"
23    url = "#"

1[[blogger.social]]
2    name = "显示名称"      # ◀️ 社交平台的显示名称
3    icon = "图标名称"      # ◀️ 图标文件名（不含扩展名）
4    url = "链接地址"       # ◀️ 点击跳转的链接

内置社交图标

Hugo-Teek 内置以下社交图标：

图标名称	说明	常用链接格式
`github`	GitHub	`https://github.com/用户名`
`gitee`	Gitee	`https://gitee.com/用户名`
`cnb`	CNB	`https://cnb.cool/u/用户名`
`qq`	QQ	`tencent://message/?uin=QQ号`
`weichat`	微信	`#` 或二维码链接
`twitter`	Twitter/X	`https://twitter.com/用户名`
`weibo`	微博	`https://weibo.com/用户名`
`email`	邮箱	`mailto:邮箱地址`

📋 完整配置示例

典型博主卡片配置

完整配置示例📋

 1# ========================================
 2# 博主卡片 (Blogger Card)
 3# ========================================
 4[blogger]
 5    # ◀️ 头像配置（建议使用 CDN 加速）
 6    avatar = "https://img.xxdevops.cn/blog/avatar/yuwen_avatar.avif?w=150&h=150&fit=crop&fm=webp&q=80"
 7    
 8    # ◀️ 卡片背景图（可选）
 9    backgroundImage = "https://img.xxdevops.cn/blog/wallpaper/bg14.avif"
10    
11    # ◀️ 圆形装饰背景图（可选）
12    circleBgImg = "https://img.xxdevops.cn/blog/avatar/yuwen_avatar.avif?w=300&h=300&fit=crop&fm=webp&q=80"
13    circleBgMask = false
14    
15    # ◀️ 基本信息
16    name = "余温Gueen"
17    shape = "circle-rotate"
18    slogan = "明心静性，爱自己"
19
20    # ◀️ 状态表情
21    [blogger.status]
22        icon = "😪"
23        size = 18.0
24        title = "困"
25
26    # ◀️ GitHub
27    [[blogger.social]]
28        name = "GitHub"
29        icon = "github"
30        url = "https://github.com/JSXGQ"
31
32    # ◀️ CNB
33    [[blogger.social]]
34        name = "CNB"
35        icon = "cnb"
36        url = "https://cnb.cool/u/yuwenGueen"
37
38    # ◀️ QQ
39    [[blogger.social]]
40        name = "QQ"
41        icon = "qq"
42        url = "tencent://message/?uin=你的QQ号"
43
44    # ◀️ 微信
45    [[blogger.social]]
46        name = "微信"
47        icon = "weichat"
48        url = "#"

🎨 图片优化建议

头像图片规格

📐 推荐尺寸

头像尺寸: 150×150 像素（显示尺寸）
实际尺寸: 300×300 像素（2x 倍图，适配高分屏）
图片格式: WebP（推荐）或 JPG
压缩质量: 80%
文件大小: 建议控制在 50KB 以内

CDN 参数示例

Imgix CDN 格式🌐 七牛云 CDN 格式🌐 又拍云 CDN 格式🌐

1# Imgix 格式
2avatar = "https://example.imgix.net/avatar.jpg?w=150&h=150&fit=crop&fm=webp&q=80"

1# 七牛云格式
2avatar = "https://example.qiniudn.com/avatar.jpg?imageView2/1/w/150/h/150/q/80"

1# 又拍云格式
2avatar = "https://example.b0.upaiyun.com/avatar.jpg!/fw/150/fh/150/quality/80"

🔧 常见问题

头像不显示

问题：头像不显示❌ 问题：社交图标不显示❌

1原因：图片链接失效或跨域问题
2解决：
31️⃣ 检查图片 URL 是否可访问
42️⃣ 使用 HTTPS 协议
53️⃣ 检查图片是否允许跨域访问
64️⃣ 尝试使用 CDN 托管图片

1原因：icon 名称错误或图标文件不存在
2解决：
31️⃣ 确认使用内置图标名称
42️⃣ 检查图标文件是否存在于主题目录
53️⃣ 自定义图标需放在 assets/icons/ 目录

配置生效检查清单

1✅ 配置文件路径正确
2✅ TOML 语法无误
3✅ 图片 URL 可访问
4✅ 使用 HTTPS 协议
5✅ 社交链接格式正确
6✅ 重启开发服务器：make dev

📝 配置模板速查

最小化配置

最小化配置📝 完整配置模板📝

1    avatar = "头像URL"
2    name = "博主名称"
3    slogan = "个性签名"

 1    avatar = "头像URL"
 2    backgroundImage = "背景URL"
 3    circleBgImg = "圆形背景URL"
 4    circleBgMask = false
 5    name = "博主名称"
 6    shape = "circle-rotate"
 7    slogan = "个性签名"
 8    
 9    [blogger.status]
10        icon = "😊"
11        size = 18.0
12        title = "状态"
13    
14    [[blogger.social]]
15        name = "GitHub"
16        icon = "github"
17        url = "https://github.com/用户名"

🎉 博主卡片配置完成！

📡

👤 作者: 余温Gueen

🔗 链接: https://wiki.xxdevops.cn/hobby/bozhu-peizhi

🌐 版权: 本站文章除特别声明外，均采用 CC BY-NC-SA 4.0 协议，转载请注明来自余温Gueen Blog！

推荐使用微信支付

推荐使用支付宝