②个人博客空间-全局配置与安全
此为个人博客网搭建与维护全指南-②个人博客空间-全局配置与安全
大概内容为:所有不需要写复杂 Vue 逻辑的全局设置。包括自动侧边栏、Trae 风格双模态 UI 背景重构、代码行号、文字红蓝字劫持,以及 Cloudflare R2 视频流跨域和 Zero Trust 页面加密的安全配置
下一篇为:个人博客空间-定制交互组件
芝士二级标题占位
首页配置
背景配置
内容配置(字体、归档、
插件工具配置(视频、文件卡片
加密页面
首页配置
修改首页 index.md
现在的首页还是 VitePress 默认的 "VitePress" 大标题。我们需要把它改成你的个人介绍,并把按钮指向你的真实内容。
打开文件:
D:\MyBlog\index.md全部替换: 用下面的代码替换里面的内容(我帮你设计了一个符合“程序员+摄影师”风格的首页)
此为一个首页内容的例子文件,不必照抄
--- layout: home hero: name: "PandaC's Space" text: "探索代码与光影的边界" tagline: CS Student / 摄影爱好者 / 终身学习者 actions: - theme: brand text: 开始阅读笔记 link: /docs/01.Coding/Hello - theme: alt text: 欣赏摄影作品 link: /docs/02.Visuals/中央公园 features: - title: 💻 技术栈 details: Java, SpringBoot, AI, Python... 记录我的 CS 进阶之路。 - title: 📷 摄影与生活 details: 用镜头捕捉光影,用文字记录思考。 - title: 📝 知识库 details: 基于 Markdown 的数字化花园,包含编程、修图、剪辑等教程。 --- <style> :root { --vp-home-hero-name-color: transparent; --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe 30%, #41d1ff); --vp-home-hero-name-background-clip: text; -webkit-background-clip: text; } </style>保存,然后运行
deploy.bat去网页刷新首页会变成一个很酷的渐变色标题,按钮直接通往笔记
自动化侧边栏
现在的 config.mjs 里的 sidebar 是手动写死的:(例子:)
items: [
{ text: 'Java 基础', link: '/docs/01.Coding/Hello' },
{ text: '我的猫', link: '/docs/02.Photography/中央公园' }
]这意味着:以后你每写一篇新笔记,除了要写文章,还得专门跑来改这个配置文件,加一行代码。 这太反人类了,也不符合“自动化”的初衷
解决方案:安装自动侧边栏插件 我们要让 VitePress 自动扫描你的文件夹,自动生成侧边栏。
安装插件: 在
D:\MyBlog目录下打开终端,输入:bashnpm install vitepress-sidebar --save-dev修改配置 (一劳永逸): 再次打开
D:\MyBlog\.vitepress\config.mjs,做最后一次大改:这一次,我们需要做两件事:
- 在文件最顶端引入插件
- 把原来的手动
sidebar删掉,换成自动配置
请直接复制下面的完整代码,覆盖你原来的
config.mjs:此为一个例子文件,不必照抄
javascriptimport { defineConfig } from 'vitepress' import { generateSidebar } from 'vitepress-sidebar' export default defineConfig({ title: "PandaC's Blog", description: "A cool CS Student's portfolio", ignoreDeadLinks: true, themeConfig: { // 1. 顶部导航 nav: [ { text: '首页', link: '/' }, { text: '个人空间', link: '/docs/01.Coding/Hello' } ], // 2. 页面右侧大纲配置 (解决你的标题显示问题) outline: { level: [2, 4], // 关键点:显示 2级 到 4级 的标题 (H2 - H4) label: '页面导航' // 把顶部的英文 "On this page" 改成中文 }, // 3. 侧边栏配置 (站远扫描版) sidebar: generateSidebar({ // 1. documentRootPath 设为 '/' (代表根目录) // 这样插件会看到完整的路径结构 'docs/01.Coding/...' documentRootPath: '/', // 2. scanStartPath 设为 null (不要钻进任何文件夹) scanStartPath: null, // 3. 关键:把根目录下的杂七杂八文件排除掉,只留 docs 里的东西 // 这样侧边栏就不会显示 index.md, package.json 这些乱七八糟的了 excludePattern: [ 'index.md', 'README.md', 'package.json', 'package-lock.json', 'deploy.bat', 'node_modules', '.vitepress', '.git' ], useTitleFromFileHeading: true, collapsed: false }), socialLinks: [ { icon: 'github', link: 'https://github.com/pandac-blog/my-blog' } ] } })保存并运行
deploy.bat
三大板块直达目录
问题分析
你的需求: 导航栏放三个大按钮:技术、摄影、英语。点击直接进入该板块的“封面页/目录页”,而不是具体的某一篇文章
核心逻辑: VitePress(以及大多数 Web 服务器)的规则是:当你访问一个目录(例如 /docs/01.Coding/)时,它会自动寻找该目录下的 index.md 文件进行展示
行动方案: 我们需要为这三个板块,分别建立自己的“门户封面” (index.md)
解决方法
第一步:完善目录结构 (建立封面)
在 Blog_Public 文件夹(也就是 docs 对应的源目录),确保结构如下,并新建缺失的 index.md:
示例:
Blog_Public/
├── 01.Coding/
│ ├── index.md <-- (新建) 这是技术板块的封面
│ ├── Java基础.md
│ └── AI学习.md
├── 02.Photography/
│ ├── index.md <-- (新建) 这是摄影板块的封面
│ └── 中央公园.md
└── 03.English/ <-- (新建) 英语文件夹
├── index.md <-- (新建) 这是英语板块的封面
└── Lesson1.md第二步:设计“封面页”内容
现在这三个 index.md 是空的,点击去会是一片白。我们需要给它们加点内容,充当“目录导览”
举例:01.Coding/index.md 的内容建议:
# 💻 技术笔记
这里记录我的计算机科学进阶之路,包含 Java 后端、人工智能探索以及前端开发心得。
## 热门文章
* [Java 基础](/docs/01.Coding/Java基础)
* [AI 学习路线](/docs/01.Coding/AI学习)
> "Talk is cheap. Show me the code."(摄影板块的 index.md 可以放一张精选大图,英语板块可以放学习计划表。)
第三步:修改导航栏配置 (config.mjs)
现在有了封面,我们就可以在导航栏直接链接到文件夹了(注意链接最后要加 /,或者直接指向文件夹名,VitePress 会自动解析到 index.md)
打开 config.mjs,修改 nav 部分:
nav: [
{ text: '首页', link: '/' },
// 1. 技术博客 (直达封面)
// 注意:这里 link 写到目录层级即可,VitePress 会自动找下面的 index.md
{ text: '💻 技术博客', link: '/docs/01.Coding/' },
// 2. 摄影作品 (直达封面)
{ text: '📷 摄影作品', link: '/docs/02.Photography/' },
// 3. 英语学习 (直达封面)
{ text: '🔤 英语学习', link: '/docs/03.English/' }
],优化侧边栏配合三大板块
既然你分了三个大区,你肯定不希望点进“英语”的时候,侧边栏还显示“Java”的目录。我们需要让侧边栏根据当前所在的板块,自动显示对应的内容
vitepress-sidebar 插件支持这种**“分栏独立目录”。我们需要修改 config.mjs 里的 sidebar 配置,不再是一股脑全扫,而是分三次扫描**
请用下面这段代码覆盖原来的 sidebar 配置:
// 侧边栏配置:分板块扫描
// generateSidebar 接受一个数组,数组里的每个对象对应一个板块
sidebar: generateSidebar([
// 1. 技术板块的侧边栏
{
documentRootPath: '/',
scanStartPath: 'docs/01.Coding',
resolvePath: '/docs/01.Coding/',
useTitleFromFileHeading: true,
collapsed: false,
excludePattern: ['index.md'] // 只排除封面页,其他不需要排除
},
// 2. 摄影板块的侧边栏
{
documentRootPath: '/',
scanStartPath: 'docs/02.Photography',
resolvePath: '/docs/02.Photography/',
useTitleFromFileHeading: true,
collapsed: false,
excludePattern: ['index.md']
},
// 3. 英语板块的侧边栏
{
documentRootPath: '/',
scanStartPath: 'docs/03.English',
resolvePath: '/docs/03.English/',
useTitleFromFileHeading: true,
collapsed: false,
excludePattern: ['index.md']
}
]),(注意:generateSidebar 如果传入一个数组 [],它就会生成多套侧边栏,VitePress 会自动匹配当前 URL 显示哪一套。)
网站的四大板块
我的需求
你现在我有一个关于个人博客网站的新问题,我目前在docs下,除了about/me.md这个个人介绍专用目录,以及之前搞过的01.Coding、02.Photography、03.English目录之外,又搞了一个04.Share目录,记录了一些软件工具分享、建站指南、生活分享、网络资源配置的内容等等,现在为了把这一个内容新添加到网站右上角的导航栏,需要改动哪些内容?MyBlog目录下的index.md要改吧,Share目录下的index.md也要改吧,还有config.mjs文件也要改吧?刚好借此机会,你也帮我把网站首页的几个按钮改为四个,刚好对应我的4个目录内容,以及下方的4个框,也是对应我的四个目录内容
后来又更新了第五板块:05.Growth,步骤同下(#^.^#)
第一步:装修新分店 (创建文件)
先建立文件夹和封面页,不然配置好了也没东西显示。
- 在
docs下新建文件夹:04.Share。 - 在里面新建
index.md(封面)。 - (可选) 再建一个
Tool.md(测试文章),方便看侧边栏效果。
docs/04.Share/index.md 内容示例:
# 💎 资源分享 (Share)
这里是我的百宝箱,记录好用的工具、避坑指南和生活碎片。
## 📂 目录导航
* [🛠 软件工具](/docs/04.Share/Tool)
* [🌐 建站指南](/docs/04.Share/建站)
> "Sharing is caring."第二步:修改“总控中心” (config.mjs)
这里要改两处:顶部导航栏 (Nav) 和 侧边栏 (Sidebar)。
请打开 .vitepress/config.mjs:
1. 修改 nav (添加第4个入口):
JavaScript
nav: [
{ text: '首页', link: '/' },
{ text: '💻 技术笔记', link: '/docs/01.Coding/' },
{ text: '📷 摄影作品', link: '/docs/02.Photography/' },
{ text: '🔤 英语学习', link: '/docs/03.English/' },
// 👇 新增这一行
{ text: '💎 资源分享', link: '/docs/04.Share/' }
],2. 修改 sidebar (添加第4个扫描规则):
找到 generateSidebar([...]) 那个数组,在里面加一个对象。
JavaScript
sidebar: generateSidebar([
// ... 原有的 01.Coding 配置 ...
// ... 原有的 02.Photography 配置 ...
// ... 原有的 03.English 配置 ...
// 👇 新增:04.Share 板块的侧边栏
{
documentRootPath: '/',
scanStartPath: 'docs/04.Share',
resolvePath: '/docs/04.Share/',
useTitleFromFileHeading: true,
collapsed: false,
excludePattern: ['index.md']
}
]),第三步:修改“门户大门” (docs/index.md)
这一步就是你想要的**“4个按钮 + 4个方块”**。
请打开 docs/index.md,替换 hero 和 features 部分:
---
layout: home
hero:
name: "PandaC's Space"
text: "探索代码与光影的边界"
tagline: CS Student / 摄影爱好者 / 终身学习者
image:
src: https://你的OSS链接/cover.jpg
alt: Cover Image
# 👇 这里配置 4 个按钮
actions:
- theme: brand
text: 💻 技术笔记
link: /docs/01.Coding/
- theme: alt
text: 📷 摄影作品
link: /docs/02.Photography/
- theme: alt
text: 🔤 英语学习
link: /docs/03.English/
- theme: alt
text: 💎 资源分享
link: /docs/04.Share/
# 👇 这里配置 4 个大方块
features:
- title: 💻 技术栈
details: Java, SpringBoot, AI... 记录我的 CS 进阶之路。
link: /docs/01.Coding/
- title: 📷 摄影与生活
details: 用镜头捕捉光影,用文字记录思考。
link: /docs/02.Photograph/
- title: 🔤 英语进阶
details: New Concept English 学习笔记与打卡。
link: /docs/03.English/
- title: 💎 资源与分享
details: 软件推荐、建站避坑、生活好物分享。
link: /docs/04.Share/
---(注意:Features 里的 link 属性需要 VitePress 较新版本支持,如果点击方块没反应,可以像我们之前那样在 details 里写 HTML 链接,或者保持现在的样子当纯展示。)
网站的五+四+一板块
26年1月11日更新
目前的五个板块是:docs/下的
01.Coding02.Visuals(从Photography改为Visuals,更贴合“视觉工坊”)博客网相关内容,均由Photography改为Visuals!笔记中若有Photography,亦不影响阅读
03.English04.Share05.Growth
然后四个板块:docs/下的
- util:工具板块,比如说todolist、Heatmap、照片墙等等
- private:私密板块
- game:游戏成品展示板块
- blender:建模、动画成品展示板块
然后是一个总归档:docs/下的
- archive.md
增加搜索框
找到 themeConfig 下的 nav,替换为以下逻辑(注意路径要对应你真实的文件夹):
themeConfig: {
// 开启本地搜索 (这是让网站变高级的第一步)
search: {
provider: 'local'
}, provider: 'local'
}解决“Logo 是空的”
没有 Logo 的网站就像没有头像的微信,由于你不想自己设计复杂的 SVG,我们有两个方案:
方案 A:使用 Emoji 或 文字 Logo (最快) VitePress 支持直接用文字或 Emoji 当 Logo
方案 B:使用图片 Logo (推荐) 既然你有阿里云 OSS,找一张你满意的照片(比如你的摄影作品截取一个局部,或者你的头像),上传到 OSS,拿到链接
操作:修改 config.mjs
export default defineConfig({
// ...
themeConfig: {
// 在 themeConfig 的最上面添加
logo: 'https://你的阿里云OSS链接/logo.png', // 支持图片
// 或者用文字:
// siteTitle: 'PandaC Space', // 左上角的文字
// ...
}
})解决“首页太空”
首页默认的只有文字。加一张高大上的配图瞬间就不一样了
1. 给 Hero 区域加图 找一张你拍的最好的照片(或者找一张赛博朋克风格的代码图),上传 OSS。
操作:修改 index.md
---
layout: home
hero:
name: "PandaC's Space"
text: "探索代码与光影的边界"
tagline: CS Student / 摄影爱好者
# 👇 加上这个 image 配置
image:
src: https://你的OSS链接/cover.jpg
alt: Cover Image
actions:
# ... 保持不变
---效果:图片会显示在标题的右侧(PC端)或下方(手机端),视觉重心立马稳住了
2. 增加页脚 (Footer) 网站底部空荡荡的也不好,加上版权信息
操作:修改 config.mjs
// ... 在 themeConfig 里添加
footer: {
message: '基于 VitePress 搭建 | 记录生活与代码',
copyright: 'Copyright © 2024-present PandaC'
},
// ...解决“作品展示不好看”
作品和文档都是 .md。对于代码笔记,默认的布局(左侧目录,右侧文章)很好。但对于摄影作品,左边有个目录栏会很干扰看图
优化技巧:为摄影作品关闭侧边栏
你可以在你的摄影作品 Markdown 文件(比如 中央公园.md)的最开头(Frontmatter 区域)
加上特定配置:
---
# 使用 'doc' 布局,但隐藏侧边栏,让图片显示区域更宽
layout: doc
aside: false # 关闭右侧大纲
sidebar: false # 关闭左侧侧边栏 (可选,如果你想沉浸式展示图片)
---
# 中央公园摄影集

这样,摄影页面就会变得很宽敞,适合展示大图
增加“元数据” (显得像个活跃的博客)
在文章底部显示“最后更新时间”和“编辑此页”,是技术博客的标配。
操作:修改 config.mjs
export default defineConfig({
// ...
themeConfig: {
// ...
// 显示最后更新时间
lastUpdated: {
text: '最后更新于',
formatOptions: {
dateStyle: 'short',
timeStyle: 'medium'
}
},
// 显示“在 GitHub 上编辑此页” (非常有极客范儿)
editLink: {
pattern: 'https://github.com/你的用户名/my-blog/edit/main/docs/:path',
text: '在 GitHub 上纠错'
}
}
})增加“关于作者”页面(已弃用)
config.mjs文件中:nav部分添加关于作者
// 优化后的导航栏
nav: [
{ text: '首页', link: '/' },
// 1. 技术博客 (直达封面)
// 注意:这里 link 写到目录层级即可,VitePress 会自动找下面的 index.md
{ text: '💻 技术博客', link: '/docs/01.Coding/' },
// 2. 摄影作品 (直达封面)
{ text: '📷 视觉工坊', link: '/docs/02.Photography/' },
// 3. 英语学习 (直达封面)
{ text: '🔤 英语学习', link: '/docs/03.English/' },
// 增加一个“关于我” (显得专业)
{ text: '关于作者', link: '/docs/about/me' }
],docs/about/me.md文件:
---
layout: doc
outline: deep
---
# 关于作者 (About Me)
👋 Hi, I'm **PandaC**.
一名热爱光影的 **CS 大学生**,正在用代码构建世界,用快门记录瞬间。
我不只是代码的搬运工,更是生活的观察者。
## 🛠 技能栈 (Tech Stack)
我的武器库:
* **Core:** Java, Python, C++
* **Web:** SpringBoot, Vue, VitePress
* **AI:** Deep Learning (Learning...), LLM Prompting
* **Tools:** Git, Docker, Cloudflare
## 📷 摄影装备 (Gear)
* **Camera:** (比如: Sony A7M4 / Fuji XT5)
* **Lens:** (比如: 24-70mm f2.8 GM)
* **Editing:** Lightroom / Photoshop / Davinci Resolve
## 🚀 经历 (Timeline)
* **2025** 🎓 预计从某大学 CS 专业毕业
* **2024** 💻 独立搭建个人博客系统,开始系统性输出技术笔记
* **2023** 🏆 获得 XX 摄影比赛优秀奖 / 校园活动主力摄影师
* **2022** 👶 编写了第一行 Java 代码
## 📮 联系我
* **GitHub:** [pandac-blog](https://github.com/pandac-blog)
* **Email:** (你的邮箱)
* **WeChat:** (或者放个二维码图片)
---
> "Stay hungry, Stay foolish."增加网页标签图标 (Favicon)
现状: 现在你浏览器标签页上(Tab)显示的可能是一个默认的 V 图标或者空白。 优化: 换成你自己的 Logo。
操作: 修改 config.mjs 的根配置区域(注意不是 themeConfig 里,而是最外层):
export default defineConfig({
title: "PandaC's Blog",
// 👇 添加这一行 head 配置
head: [
['link', { rel: 'icon', href: 'https://你的OSS链接/favicon.ico' }]
],
themeConfig: { ... }
})**无底板图片:**网站的favicon图标也是logo的一种,但是是无底板图片
自定义 404 页面(已弃用)
总而言之、言而总之:这种方式有bug不适合。
现状: 现在的 404 页面是默认的。 优化: 搞个有趣的 404 页面。
操作: 直接在 docs 根目录下建一个 404.md:
---
layout: page
---
# 404 Not Found 🚧
**哎呀,迷路了!**
你寻找的页面可能去**中央公园**拍照了,或者正在**修 Bug**。
[👉 返回首页](/)开启代码块行号 (Code Line Numbers)
博客里肯定会有很多代码。默认的 VitePress 代码块是没有行号的。开启行号后,代码看起来会更像 IDE(VS Code),非常专业,方便别人引用(比如:“看第 5 行代码...”)
操作步骤: 打开 config.mjs,在 themeConfig 的外面(也就是和 title、description 平级的地方),添加 markdown 配置:
export default defineConfig({
title: "PandaC's Blog",
// ... 其他配置
// 👇 添加这一块
markdown: {
lineNumbers: true // 开启行号显示
},
themeConfig: {
// ... 你的主题配置
}
})加密页面
我的需求
创建一个私密的日记/心得板块(例如 docs/diary)
安全性:需要真正的访问拦截,而不是简单的前端密码(防君子不防小人)
隐私性:私密文章的标题、日期不能出现在首页的“近期文章”、“归档”或“热力图”中
源码保护:GitHub 仓库不能被公开查看
功能介绍
采用 “代码私有 + 访问控制 + 数据隔离” 的企业级安全方案
- 物理隔绝:源码在 GitHub 私有仓库,外人无法查看 Markdown 源文件
- 访问拦截:使用 Cloudflare Zero Trust,在网络层直接拦截未授权访问,通过邮箱验证码登录
- 数据清洗:修改本地构建脚本,确保私密文章不会被打包进公共数据(JSON)中
实现方法
线上安全配置 (Cloudflare + GitHub)
这部分实现了“进不去、看不了源码”。既然已经用了 Cloudflare 部署,有一套零代码、企业级安全、且免费的终极方案:Cloudflare Access (Zero Trust) + 私有仓库
第一步:把 Github 仓库设为 Private (私有)
这是物理隔绝。只要仓库是私有的,没人能通过 Github 看到你的日记源码
去 Github 仓库页面 -> Settings
拉到最下面 Danger Zone -> Change repository visibility
改为 Private
注:Cloudflare Pages 支持部署私有仓库,不影响你网站上线
第二步:配置 Cloudflare Access (给特定页面加锁)
Cloudflare 有一个功能叫 Zero Trust,可以给网站的特定路径(比如 /diary)加一个极其强大的验证层。
进入 Cloudflare 控制台
点击左侧侧边栏的 Zero Trust(首次使用需开通,免费版支持 50 人,需设置 TeamName 并绑定 PayPal/信用卡,0扣费)
创建应用 (Application)
- 在 Zero Trust 面板中,点击 Access -> Applications -> Add an application
- 选择 Self-hosted
配置保护路径:
Application name: 随便填,比如 "My Diary"
Session Duration: 比如
1 Month(输一次密码管一个月)Subdomain: 你的博客域名(如
pandac-blog.com)Path: 填
docs/diary(这就是你要保护的目录)设置访问规则 (Policy):这部分要先配置好,然后再进入“Add an application”页面进行选择Policy
Rule name: "Only Me"
Action:
AllowConfigure rules:
- Selector: 选择
Emails - Value: 填你自己的 Gmail 邮箱(⚠️强烈建议:QQ/163 邮箱极易拦截 Cloudflare 验证码,务必使用 Gmail)
- Selector: 选择
然后保存即可
本地数据隔离(VitePress Config + Markdown)
这部分实现了“搜不到、看不见标题”
第一步:目录与文件设置
建立目录:
docs/diary/Frontmatter 设置:在私密文章头部添加
search: false,防止被站内搜索索引。yaml--- title: 我的日记 date: 2026-01-01 search: false # <--- 关键!禁止搜索索引 ---
第二步:修改数据加载器 (Data Loaders)
为了防止私密文章出现在“首页列表”、“归档页”和“热力图”中,需要修改 docs/utils/ 下的 .mjs 文件。
- 修改对象:
posts.data.mjs和activity.data.mjs - 修改内容:统一使用双重过滤(Glob 排除 + JS 过滤)
以 posts.data.mjs 为例(activity.data.mjs 同理):
import { createContentLoader } from 'vitepress'
// 1. Glob 模式排除:使用 !**/private/** 通杀匹配
export default createContentLoader(['docs/**/*.md', '!**/private/**'], {
includeSrc: false,
render: true,
transform(rawData) {
return rawData
.filter(page => {
// ... 原有过滤逻辑 ...
// 2. JS 双重保险:如果 URL 包含 private,直接踢出
if (page.url.includes('/private/')) return false;
return true;
})
// ... 后续逻辑 ...
}
})最终效果
路人访问:
- 在首页、归档、热力图完全看不到私密文章的痕迹
- 即使手动输入
pandac-blog.com/docs/diary/,页面会被 Cloudflare 拦截,显示登录框
本人访问:
- 输入链接 -> 拦截页面 -> 输入邮箱 -> 接收 6 位验证码 -> 验证通过
- 成功进入,像浏览普通文章一样阅读日记
