橘子の博客

一、核心文件职责

`layout.tsx` — 全局外壳

XHBlogs/app/layout.tsx 是 Next.js App Router 的根布局，它定义了：

职责具体内容HTML 元数据页面标题、图标、SEO 描述字体加载Geist、Noto Serif SC 等全局字体全局 Provider主题切换 (ThemeProvider)、音乐播放 (MusicProvider)全局 UI 组件背景特效、浮动播放器、CyberCat、启动画面、弹幕背景全局样式globals.css、Tailwind 基础样式

layout.tsx 里的东西会出现在博客的每一个页面上。 导航栏、背景、播放器这些"壳"都在这里。

所以说page.tsx 只负责它自己那条路由的内容部分，然后被套进 layout.tsx 的外壳里。

二、update.py 覆盖规则速查

update.py 从上游 XinghuisamaBlogs 拉取最新代码，只覆盖它名单里的文件

会被覆盖：

XHBlogs/components/        — 所有公共组件
XHBlogs/app/**/page.tsx    — 所有页面的 page.tsx
XHBlogs/app/layout.tsx     — 根布局
XHBlogs/app/globals.css    — 全局样式
my-blog-manager/cms_core/  — CMS 后端
my-blog-manager/components/— CMS 组件
my-blog-manager/app/**/page.tsx — CMS 页面

不会被覆盖：

XHBlogs/data/              — 数据文件 (albums.ts, friends.ts, projects.ts)
XHBlogs/posts/             — 文章 .md
XHBlogs/chatters/          — 说说 .md
XHBlogs/moments/           — 瞬间 .md
XHBlogs/siteConfig.ts      — 全站配置 
XHBlogs/public/            — 静态资源 
my-blog-manager/data/      — CMS 数据文件
my-blog-manager/siteConfig.ts — CMS 配置

三、实践

1：加一个独立页面（最推荐，零冲突）

直接在 XHBlogs/app/ 下新建目录 + page.tsx，Next.js 自动识别为路由。

 XHBlogs/
 └── app/
     └── tools/              
         └── page.tsx        ← 访问 /tools 即可看到

优点： 完全独立，不需要改动任何已有文件，永远不会冲突。

B：全局组件（但需要改 layout.tsx / Navbar.tsx）

因为我的功能需要出现在每个页面上（比如全局公告栏、回到顶部按钮），必须改 layout.tsx 或 Navbar.tsx。

做法：把自定义代码放在独立目录，用 git patch 管理改动。

 步骤 1：创建自定义组件
 XHBlogs/
 └── custom/                 ← 扩展目录（update.py 不碰）
     ├── index.ts            ← 统一导出入口
     └── BackToTop.tsx       ← 组件
 
 步骤 2：在 layout.tsx 中引入组件，然后生成补丁
 git diff HEAD -- XHBlogs/app/layout.tsx > XHBlogs/custom/layout-custom.patch

update.py 恢复： 一行命令全自动恢复

 git apply XHBlogs/custom/layout-custom.patch
 git apply XHBlogs/custom/navbar-custom.patch

C：改已有页面

给已有的页面（比如首页 page.tsx）加模块。

把新增模块写在 custom/ 里，在 page.tsx 中引入。同样，跑 update.py 后补回 import 即可。

四、siteConfig.ts 作为功能开关

siteConfig.ts 不在覆盖名单里，所以把它当作自定义功能的控制面板：

Vercel部署：

XHBlogs (本地博客源码)
    │
    ▼ CMS → deploy.py → git push
OriginBlogsS2 (GitHub 源码仓库)
    │
    ▼ Vercel 检测到 push → next build

跑完 update.py 后、触发 Vercel 部署前，两条命令：

 git apply XHBlogs/custom/layout-custom.patch
 git apply XHBlogs/custom/navbar-custom.patch

结论：patch 文件在 custom/ 安全区里，不会被覆盖。两条命令即可恢复全部自定义功能。

搞定！！！😋😋😋