前端实现与难点

状态：未准备（需要确认哪些是本人二次开发）

实现概览

源码根目录：blog。路径均相对该目录。

Next.js / Contentlayer 组织文章和元数据，Tailwind 负责响应式布局，客户端组件承担滚动目录、主题和贡献动画。简历优先讲个人新增交互，内容构建链路用于说明框架理解。

难点与取舍

1. 目录活动项与滚动监听

具体问题与背景：长文章需要定位当前章节，桌面端与移动端的可用空间不同。
我的实现（候选，待确认）：筛选二三级标题，读取标题位置确定活动项；使用被动 scroll 监听和 requestAnimationFrame 调度，移动端折叠、桌面端 sticky 展示，卸载时清理。
备选方案：IntersectionObserver；每次 scroll 都直接计算并更新。
选择理由与限制：当前方案直接、易定位；扫描标题仍有成本，不能写成 O(1) 或零开销。这里没有使用 IntersectionObserver。
结果与验证方式：检查顶部偏移、快速滚动、窗口缩放、中文锚点和空目录；性能收益待测。
代码路径 / 证据：components/ArticleToc.tsx。

2. 贡献数据与动画分离

具体问题与背景：贡献数据需要网络获取，动画依赖浏览器和逐帧状态。
我的实现（候选，待确认）：服务端获取数据并设置一小时再验证，客户端使用 SVG、ref、useMemo 和 rAF 驱动展示；处理请求失败、页面隐藏与减少动画偏好。
备选方案：客户端直接请求全部数据；直接嵌入第三方静态图。
选择理由与限制：能分别维护请求与交互；第三方服务仍有可用性依赖。动画直接修改 SVG 属性，需要解释和 React 渲染的职责边界。
结果与验证方式：检查失败提示、暗色模式、页面切换和反复挂载；性能数据待测。
代码路径 / 证据：components/GitHubHeatmap.tsx、components/GitHubContributionBoard.tsx、components/github-contributions.ts。

3. MDX 页面与 SEO 配置

具体问题与背景：本地文章需要一致的路由、渲染与分享信息。
我的实现（候选，待确认）：配置 Contentlayer 派生字段和 MDX 插件，结合静态参数、动态元数据、结构化数据和 sitemap 输出文章信息。
备选方案：CMS / 数据库；纯客户端渲染文章。
选择理由与限制：适合单人维护；很多能力可能来自模板 / 插件，只有本人修改过的部分才能写“实现”。SEO 配置不代表访问量增长。
结果与验证方式：查看生成 HTML 的 title、description、结构化数据，检查 sitemap 与草稿过滤。
代码路径 / 证据：contentlayer.config.ts、app/blog/[...slug]/page.tsx、app/sitemap.ts。

待完善项

补模板来源与个人改动清单，优先保留能用提交记录说明的交互。
不写尚未验证的搜索、评论、订阅、图片懒加载收益等功能和成果。
性能待测：同一设备、构建模式和网络下使用 Lighthouse / DevTools 多次测量 LCP、CLS、资源体积；只有修改前后的可比记录才能写提升幅度。