个人主页的项目结构治理记录
记录项目如何从多套部署链路整理为清晰、稳定、可检查的 Vercel-only 结构。
· 开发笔记
整理前的问题
项目早期同时保留了多套部署文件、代理服务和历史资源。它们虽然记录了不同阶段的尝试，但也让根目录越来越复杂。
常见问题包括：
多个部署入口表达相同目标；
运行脚本、服务器代码和前端代码边界模糊；
本地构建产物反复出现在根目录；
静态资源保留与删除缺少自动检查；
文档描述和实际部署方式逐渐产生偏差。
当前目录边界
整理后的主要职责如下：
| 目录 | 职责 | | --- | --- | | src | Vue 前端源码 | | src/features | 按功能组织的页面组件 | | src/services | 浏览器端 API 请求 | | api | Vercel Function 入口 | | server | 本地与线上共用的 Node 服务 | | scripts | 质量检查与健康检查 | | public | 图片、字体和公开静态文件 |
这些边界让每个文件都有明确归属，也让后续新增博客功能时可以继续放在现有目录中。
自动检查的价值
项目现在通过结构检查维护根目录白名单、必要路径、静态资源和环境变量引用。
完整检查命令如下：
npm run check它会依次执行：
项目结构检查；
ESLint；
Vite 生产构建；
PWA 构建。
完成验证后，本地产物可以通过下面的命令清理：
npm run clean:local最终原则
文件路径精简的目标不是追求目录数量最少，而是让源码、配置、服务、内容和本地产物各自处在稳定边界中。