自建技术博客实战（一）：Next.js 架构与深浅色主题设计

一、为什么要做这个项目内容自主Markdown 文件即文章可 Git 管理、可静态托管体验统一深色科技感 可选浅色适配长时间阅读能力扩展在博客之外增加「工具专栏」把地图、语音、抠图等能力收进同一站点。技术栈选用Next.js 16App Router React 19 Tailwind CSS v4兼顾 SSG 性能与按需 API 路由。二、整体架构tech-portfolio/ ├── content/posts/ # Markdown 文章319 篇 ├── public/ # 静态资源logo-cat.svg 等 ├── scripts/ # 迁移、静态构建脚本 └── src/ ├── app/ # 页面与 API 路由 ├── components/ # UI 组件 ├── config/ # site.ts、tools.ts 配置 └── lib/ # posts、markdown、各工具逻辑2.1 路由设计路径类型说明/静态首页技能卡片 最新文章/blog静态文章列表/blog/[slug]SSG单篇文章generateStaticParams预生成/tools/*静态壳 客户端工具页 UI/api/tools/*动态声音复刻、抠图等需 Node 运行时思路页面尽量 Server Component只有主题切换、地图、上传表单等交互部分使用use client。2.2 双模式构建next.config.ts根据环境变量切换输出模式constisStaticExportprocess.env.STATIC_EXPORTtrue;constnextConfig{...(isStaticExport?{output:export}:{output:standalone}),// ...};npm run buildstandalone保留src/app/api适合带工具的服务器部署npm run build:static临时移走api目录后output: export产物在out/适合 Gitee Pages / 对象存储纯静态托管。这是典型的「博客可静态、工具要 API」拆分策略。三、配置驱动避免硬编码3.1 站点信息src/config/site.ts导航、作者、技能矩阵、外链集中在一处exportconstsiteConfig{name:jingling,nav:[{href:/,label:首页},{href:/blog,label:博客},{href:/tools,label:工具},{href:/about,label:关于},],skills:[/* 前端 / GIS / 移动端 / 后端 / 架构 */],};HeaderNav读取nav渲染Footer同步改导航只改一个文件。3.2 工具注册表src/config/tools.ts每个工具一条元数据slug、标题、描述、图标、标签、requiresEnv工具列表页与ToolsSubnav自动派生新增工具只需注册 新建页面。注意requiresEnv应写环境变量名如NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN不要写真实 Token避免被 GitHub Push Protection 拦截。四、深浅色主题实现4.1 选型next-themesdata-theme// ThemeProvider.tsx NextThemesProvider attributedata-theme defaultThemedark enableSystem themes{[light, dark, system]} 根节点layout.tsx设置data-themedark作为首屏默认值减少闪烁。4.2 语义化 CSS 变量在globals.css中为[data-themelight]与[data-themedark]分别定义一套变量[data-themedark]{--background:#04060d;--accent-violet:#a78bfa;--accent-cyan:#22d3ee;--gradient-brand:linear-gradient(135deg,#8b5cf6 0%,#06b6d4 100%);/* ... */}组件只使用语义类名例如text-heading→color: var(--text-heading)glass-card→ 毛玻璃卡片背景btn-primary→ 渐变主按钮好处换主题不改组件Mapbox 地图样式也可在客户端根据useTheme()切换dark-v11/light-v11。4.3 主题切换按钮ThemeToggle调用useTheme()在light/dark/system间循环样式复用.theme-toggle与导航按钮视觉一致。五、品牌与布局组件5.1 小猫 Logo将原字母J徽章替换为SiteLogoSVG SiteLogoBadge徽章底--gradient-brand紫青渐变猫身currentColor白色眼睛--logo-cat-eye随深浅色微调青色。顶栏、页脚、关于页复用同一组件尺寸通过sm | md | lg控制。5.2 页面壳模式工具页、关于页等遵循统一结构div classNamesite-container py-12 md:py-16 PageHeader label... title... description... / ToolsSubnav / {/* 仅工具相关页 */} div classNameglass-card mt-8 p-5 md:p-8 {/* 具体工具组件 */} /div /div工具专用样式以tool-*为前缀集中在globals.css「工具专栏」段落与博客article-*样式分离避免互相污染。5.3 返回顶部BackToTop监听滚动超过阈值显示固定右下角按钮使用--shadow-glow与主题变量不依赖第三方库。六、本系列后续文章篇目主题一本文架构、主题、配置、构建模式二CSDN 迁移、Markdown 渲染、图片处理三工具专栏地图、声音复刻、rembg 抠图七、小结App Router SSG适合大量博客文章API 路由按需保留给工具。CSS 变量 next-themes是轻量、可控的主题方案比逐组件改 Tailwind 暗色类更易维护。config 驱动让导航、工具列表与元数据单一数据源利于扩展。双构建脚本在「纯静态托管」与「带后端工具」之间取得平衡。下一篇将介绍如何把 CSDN 历史文章批量迁到content/posts/以及正文渲染、目录、图片代理等实现细节。