最后更新: 2026年11月18日
一个温馨可爱的个人博客,以虚拟歌手洛天依为主题,适合记录生活感悟和技术学习心得。
Live站点: https://blog.xinchengp.cn
- Next.js 16.4.3 - App Router,开发模式使用 Turbopack,静态导出构建使用 webpack
- React 19.x - 函数组件 + hооk
- TypeScript 5.x - 严格模式,类型安全
- Node.js 24 - 运行环境要求(engines 强制 >=24.0.0)
- Tailwind CSS 4 - 原子化CSS,深色模式支持
- shadcn/ui 语义化 CSS 变量 - 统一语义化设计令牌,主题切换平滑过渡
- CSS Variables - 主题色系统,锁定天依蓝配色
- Framer Motion - 动画和过渡效果
- next-themes - 主题切换
- marked / react-markdown - Markdown渲染
- gray-matter - Frontmatter解析
- highlight.js / react-syntax-highlighter - 代码语法高亮
- remark-gfm / remark-math / rehype-katex - Markdown扩展(表格、数学公式)
- rehype-sanitize / remark-emoji - Markdown 安全过滤与表情支持
- recharts - 数据可视化图表(更新日志统计、技能雷达图)
- howler - 音乐播放器核心(HowlerPlayerManager 单例管理)
- @tsparticles/react - 粒子动画背景
- leaflet / react-leaflet - 旅行足迹地图
- katex - 数学公式渲染
- dompurify - XSS防护
- qrcode.react - 二维码生成(博客分享)
- octokit - GitHub API集成
- simple-git - Git操作(后台推送)
- chinese-lunar-calendar - 农历节日计算
- lucide-react / @heroicons/react - 图标库
- fuse.js - 站内全文搜索(客户端模糊检索)
- @tailwindcss/typography - Markdown 排版样式
- ESLint 9.x + eslint-config-next - 代码检查(core-web-vitals + typescript recommended)
- tsx - TypeScript脚本执行器
- sharp - 图片处理
- express / compression - 本地静态预览服务器
- Electron 34 - 桌面应用打包
- 互动看板娘 - 可爱的洛天依陪你逛博客,支持音乐/主题/页面联动与彩蛋消息
- 问天依(AI 导览) - Live2D 控制区「问天依」按钮唤起问答面板:知识库覆盖全站(文章正文、生活动态、131 篇开发日志、站点功能说明,共 270+ 内容块,另含全部文章清单/分类清单/最新发布/最近更新等派生块),「有没有讲 XX 的文章」「博客有什么功能」「最近更新了什么」都能精准作答并给出带类型图标的可点击来源卡;检索按问题意图筛选资料类型(找文章不会拿日志冒充),当前功能以站点说明为准、历史日志只用于回答更新历史;模型只允许用【编号】引用来源(根治幻觉标题),「没找到」类回答不挂无关来源卡;成本三重闸门(单人 8 问/小时、全站 200 问/天、无相关资料不调用模型;开发阶段不缓存答案,改动即时生效),内容更新后
npm run index:blog一键重建索引 - 消息优先级系统 - 配置化消息模板 + 优先级队列(彩蛋 10 > 紧急 9 > 高 7 > 中 5 > 普通 3 > 低 1),高优先级可中断当前消息,彩蛋/烟花/歌词模式互斥屏蔽
- 上下文感知 - 根据滚动速度、停留时长、深夜活跃、回访次数等行为智能推送消息(30秒冷却)
- 一言接入 - 原生 fetch 调用一言 API,由 React 组件生命周期托管定时器,8秒超时静默降级
- 精选音乐 - 内置多首洛天依歌曲
- 主题配色 - 以天依蓝为主色调,清新自然
- 轻松写文 - 支持Markdown格式,简单易用
- 时光河流归档 - 水平波浪时间线布局,按年份自动分组,支持标签点击筛选
- 文章目录 - 自动生成目录导航,滚动高亮定位
- 相关文章 - 基于分类和标签的相关推荐
- 分享面板 - 支持链接复制和二维码分享
- 评论互动 - 基于 Twikoo 的评论系统,后端部署在 Cloudflare Workers + D1,无需自建服务器
- 阅读统计 - 自动计算阅读时间
- 隐藏文章 - 支持标记文章为隐藏状态
- 时效性提示 - 技术文章自动显示更新时效提示
- 多媒体渲染 - 支持KaTeX数学公式、视频文件自动渲染为播放器、B站视频嵌入
- 长代码折叠 - 超过30行的带语言代码块自动折叠,支持展开/收起与完整复制,避免长代码拖慢页面
- 文件下载链接 - Markdown链接支持download属性,可直接提供本地文件下载
- 路由级兜底 - 各主要页面提供
loading.tsx骨架屏与error.tsx错误兜底,统一为 RouteSkeleton / RouteErrorFallback 组件,弱网或异常时不再白屏 - 博客渲染重构 - 拆分 BlogMarkdownBase / ServerBlogMarkdown / BlogArticleImage / BlogArticleIframe / ThemeAwareCodeBlock,服务端与客户端渲染统一
- Markdown 安全 - rehype-sanitize 配置独立 sanitizeSchema,过滤危险标签属性
- RSS 订阅 - 内置
/rss.xml订阅源(构建期静态生成),与 sitemap 共用统一的博客扫描工具(blogScanner),页脚提供订阅入口 - 系列导航 - 文章 frontmatter 声明
series/seriesOrder后,详情页元信息栏下方出现一行式系列进度条:系列名 + 当前进度 + 上一篇/下一篇快捷跳转,「全部 N 篇」可展开完整目录(当前篇高亮) - RSS 全文输出 -
/rss.xml在摘要之外提供content:encoded全文(构建期 Markdown→HTML),站内图片/链接自动补全为绝对地址 - 继续阅读 - 文章滚动进度自动落盘(按 2% 步进节流),下次打开浮出「上次读到 N%」提示一键跳转;记录 30 天过期、上限 50 篇防膨胀
- PWA -
manifest.webmanifest+ 由站点头像生成的图标(scripts/generate-pwa-icons.mjs),博客可安装到桌面/主屏幕,离线由既有 sw.js 兜底 - 代码块行高亮 - 行号之外支持围栏 meta 标记
```js hl=1,3-5(兼容highlight=、逗号分隔与区间),天依蓝底色 + 左侧竖条
- 浏览量统计 - 自托管 Cloudflare Worker + D1(
cloudflare/interactions),文章页元信息栏与列表卡片角标展示全站浏览量;按「路径 + 天 + 访客哈希」去重,不存原始 IP,每日 cron 清理 90 天前明细,接口不可用时自动隐藏不打扰阅读;后台仪表盘可凭ADMIN_TOKEN查看总览与各篇明细 - 友链巡检 -
npm run check:friends检查友链可达性与响应耗时;结果随构建发布,友链卡显示在线/离线状态点;GitHub Actions 每周定时巡检 - 新文章通知 - 推送含新文章的提交后,
notify.yml自动发送 Telegram 频道消息(带封面)并调用 Worker 群发邮件,按 slug 幂等防重发 - 邮件订阅 -
/subscribe聚合页:RSS / Telegram / 邮件三渠道;邮件为 Resend 双重确认,正文带一次性退订链接,未配置时自动隐藏表单 - 分享卡片 - 文章分享面板一键生成竖版分享图(Canvas 手绘:天依蓝渐变 + 封面 + 标题摘要 + 二维码),可直接下载或长按转发,跨域封面自动降级
- Howler驱动 - 基于 Howler.js 的全局播放管理器,播放状态跨页面持久化
- 侧边滑出 - 隐藏在屏幕左侧,鼠标移入热区或点击独立按钮滑出
- 播放模式 - 顺序、随机(防重复)、单曲循环
- 歌词显示 - 支持歌词面板与高亮滚动
- 播放历史 - 记录最近播放,快速回听
- 精细控制 - 进度条拖拽、音量滑块、播放列表定位
- 动态发布 - 记录生活点滴,支持置顶功能
- 时间显示 - 精确到秒的时间记录
- 九宫格图片 - 图片以九宫格布局展示,支持灯箱预览
- 画廊选图 - 发布动态时可直接从画廊选择图片
- 隐藏动态 - 支持标记动态为隐藏状态
- 侧边栏组件 - 待办事项、时间进度、节日倒计时
- 图片管理 - 集中管理博客图片资源
- 图床驱动 - 图片托管于图床,构建期抓取、浏览器端支持实时刷新
- 分类筛选 - 按分类浏览和筛选图片
- 图片预览 - 灯箱放大控制、左右翻页
- 递归扫描 - 自动递归扫描子目录图片
- 目录树导航 - 子目录快速导航和数量统计
- 开发日志 - 记录项目开发过程和功能更新
- 时间线展示 - 按时间顺序展示更新历史
- 分类标记 - 区分功能新增、优化、修复等类型
- 数据可视化 - 时间趋势折线图和类型分布环形图
- 成就标签 - 根据提交数量和日志规模自动计算成就
- 本地管理 - 开发环境访问
/admin进行后台管理 - 内容管理 - 博客、动态、更新日志的增删改查与编辑
- 画廊管理 - 本地图片上传与远程图床管理
- 待办管理 - 待办事项的增删改查操作
- 代码备份 - 本地代码备份快照管理,支持密码保护
- GitHub推送 - 直接推送更改到远程仓库
- 站点设置 - 站点配置在线调整
- 技能雷达图 - Recharts雷达图展示技能水平,支持悬停查看详情
- 旅行足迹 - Leaflet地图标记旅行地点
- 游戏库 - 展示常玩游戏收藏
- 设备卡片 - 翻转动画展示常用设备
- 深色模式 - 自动跟随系统或手动切换,暗色图片智能滤镜
- 浏览器检测 - 自动检测浏览器兼容性并提示
- 代码复制 - 代码块一键复制功能
- 外链安全守卫 - 全局拦截站外链接点击,弹出跳转提醒(/redirect 中转页 + 全站事件委托守卫),支持继续访问/返回,尊重 Ctrl/Cmd 新标签页习惯
- 相关链接页 - 品牌图标识别、搜索与分类导航,视觉规范统一
- 友链申请 - 友链页面新增申请占位卡,统一卡片样式与交互
- 网站统计 - 接入51la统计分析
- SEO优化 - 自动生成robots.txt、sitemap.xml 和 RSS 订阅源(/rss.xml)
- 安全防护 - XSS防护、CSP策略(外部来源白名单统一登记于
src/utils/cspSources.ts,生产环境移除 unsafe-eval)、防劫持检测、外链跳转拦截;后台认证 Token 存储于 sessionStorage(会话级,关闭标签页自动失效) - 实用工具 - 站内工具(拼音转换器、Markdown编辑器、洛克王国阵容搭配模拟器)+ 外部开源工具收录(CNC G 代码生成、自动弹原琴、B站弹幕爬取、二维码生成器、洛天依图床管理工具),支持仓库直达入口
- 需要安装 Node.js 24.0 及以上版本(package.json engines 强制要求)
- npm 10.0 及以上版本
- 安装完成后,打开命令行工具
-
获取代码
git clone https://github.com/XinChengP/OxygenBlogPlatform.git cd OxygenBlogPlatform -
安装依赖
npm install
-
启动博客
npm run dev
-
访问博客 打开浏览器,输入
http://localhost:7120即可看到博客(开发端口固定为7120)
局域网访问提示:开发服务器默认只允许
localhost/127.0.0.1。 如需从局域网或 Tailscale 访问,请在.env.local中设置DEV_ALLOWED_ORIGINS=192.168.x.x,100.x.x.x(逗号分隔)。 后台 actions 没有额外的服务端鉴权,请仅在可信网络中开启。
- 在
src/content/blogs文件夹中创建新的Markdown文件(.md结尾) - 在文件开头添加文章信息,示例:
--- title: "文章标题" date: "2025-12-31" updatedAt: "2025-12-31" # 可选:文章更新时间 category: "生活感悟" tags: ["日常", "洛天依"] excerpt: "这里是文章的简短摘要" coverImage: "/Blogabout/文章名/cover.png" # 可选:封面图片路径 hidden: false # 可选:设置为true隐藏文章 ---
- 接下来用Markdown格式写正文内容
- 在
src/content/moments文件夹中创建新的Markdown文件(.md结尾) - 在文件开头添加动态信息,示例:
--- id: "1" time: "2026-09-22 10:30:00" pinned: false # 可选,设置为true可置顶动态 hidden: false # 可选,设置为true隐藏动态 tags: ["测试", "动态"] images: ["/Momentsabout/图片1.jpg", "/LTY_Picture/图片2.png"] # 可选,支持多张图片 ---
- 接下来写动态内容
- 九宫格布局: 图片会以传统九宫格的形式排列,正方形缩小显示
- 图片预览: 点击图片可以放大显示,支持左右翻页
- 高级放大功能: 支持精细的缩放控制(+/-/0键)、鼠标拖拽查看、缩放百分比显示
- 加载状态: 图片加载过程中显示加载动画,提升用户体验
- 错误处理: 图片加载失败时显示错误信息并提供重试按钮
- 图片格式: 建议使用WebP格式,每张图片大小不超过5MB
- 图片来源: 支持两种图片添加方式:
- 本地上传: 直接从本地设备上传图片,自动压缩和存储
- 画廊选择: 从博客的画廊(gallery)中选择已有的图片,支持按分类筛选
- 日志位置:
src/content/changelogs/目录 - 内容格式: Markdown格式,frontmatter 中 type 字段区分类型
- 自动展示: 在更新日志页面按时间线展示
- 后台管理: 开发环境可通过
/admin/changelogs可视化管理
本项目已配置自动部署流程(.github/workflows/deploy.yml):
- Fork 本仓库 到你的GitHub账号
- 启用 GitHub Pages:仓库Settings → Pages → Source 选择 GitHub Actions
- 推送代码:推送到 main 分支即自动触发构建部署(也可在Actions页面手动触发)
- 等待部署:GitHub Actions 自动完成以下步骤:
- 安装依赖(Node.js 24环境)
- 执行
npm run build:pages静态导出(构建期自动生成 sitemap.xml) - 部署到 GitHub Pages
部署时的环境变量已内置在 deploy.yml 中,本地部署需自行配置:
# 生产环境 (.env.production) - 自定义域名模式(当前使用)
STATIC_EXPORT=true # 启用静态导出
NEXT_PUBLIC_SITE_URL=https://blog.xinchengp.cn
CUSTOM_DOMAIN=true # 使用自定义域名,无路径前缀
# 生产环境 - GitHub Pages 默认域名模式
STATIC_EXPORT=true
NEXT_PUBLIC_SITE_URL=https://你的用户名.github.io
NEXT_PUBLIC_GITHUB_REPO_NAME=你的仓库名
NEXT_PUBLIC_BASE_PATH=/你的仓库名 # GitHub Pages路径前缀
CUSTOM_DOMAIN=false- 在GitHub仓库Settings → Pages中绑定你的域名
- 设置环境变量
CUSTOM_DOMAIN=true和NEXT_PUBLIC_SITE_URL=你的域名 - 推送代码后等待部署完成
本项目支持使用 Electron 34 打包为桌面应用:
# 运行桌面应用
npm run electron- Node.js版本:必须使用Node.js 24或以上版本(engines字段强制要求)
- 依赖安装:如果安装依赖失败,尝试使用
npm install --legacy-peer-deps - 图片大小:建议图片大小不超过500KB,确保加载速度
- 文章命名:文章文件名建议使用英文或拼音,避免特殊字符
- 本地测试:每次修改后,建议先在本地测试再推送到线上
- 构建命令:静态导出必须使用
npm run build:pages(由 build-pages.js 包装),它以 try/finally 保证 Server Actions 的临时替换与恢复——即使构建失败也会还原,不会残留空实现文件 - 开发端口:开发服务器固定使用7120端口,桌面应用默认连接该端口
- 浏览器兼容:建议使用现代浏览器(Chrome、Firefox、Safari、Edge)以获得最佳体验
- 隐藏内容:隐藏的文章和动态仅在后台可见,构建后不会显示在前台
- 敏感变量:不要在 .env.local 中设置 NEXT_PRIVATE_STATIC_EXPORT,否则开发服务器会进入静态导出模式,导致后台所有操作返回空数据
- 静态生成 - 加载速度快,SEO友好
- 免费托管 - GitHub Pages自动部署,无需服务器
- 易于定制 - 主题和功能可根据需求调整
- 持续更新 - 定期优化和添加新功能
- 类型安全 - 使用TypeScript确保代码质量
- 响应式设计 - 适配各种设备屏幕
- 桌面支持 - 可打包为桌面应用
MIT License - 可自由使用和修改
🌸 一个温馨的小天地,记录生活与成长的美好时光