EmDash CMS 项目脚手架与目录布局

发布于 2026-04-08 作者 Emdash Cms Everything

面向读者

在以下场景使用本指南：你从空仓库开始，希望目录结构能支撑：

• 日常编辑内容变更
• 不破坏 CMS 假设的前台迭代
• 日后从本地开发迁移到 Cloudflare

目标不是最聪明的文件夹树，而是降低长期维护成本。

先定运行时取舍

在创建文件前，先决定未来 30～90 天主要优化哪条路径：

• Node.js + SQLite：本地上手最快、运维最简单
• Cloudflare Workers + D1 + R2：生产 SSR、托管存储、与 EmDash 插件模型更贴合

若团队仍在验证内容策略，可先选 Node.js，但从第一天起保留 Cloudflare 友好命名。这样避免早期平台锁定，同时迁移仍直截了当。

推荐基线目录布局

your-emdash-site/
├── src/
│   ├── components/            # 仅可复用 UI 片段
│   ├── layouts/               # 共用页面外壳
│   ├── pages/                 # Astro 路由
│   ├── lib/                   # 领域逻辑与集成
│   ├── styles/                # 全局与共享样式 token
│   └── live.config.ts         # 实时内容集合映射
├── seed/                      # 脚手架/演示用种子数据
├── public/                    # 静态资源（favicon、静态图等）
├── docs/                      # 产品文档与编辑内容（MDX）
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── emdash-env.d.ts

若现有项目用 utils/ 而非 lib/，可暂时保留；仅在能明确所有权规则时再重命名。

目录所有权模型

结构只有在所有权清晰时才有效：

• src/components：仅展示；不直接调数据库或存储
• src/layouts：共用框架（head、导航框、页脚壳层）
• src/pages：路由组合与渲染的数据接线
• src/lib：业务规则、数据适配器与平台胶水代码
• seed：新环境可复现的基线内容

这种划分能防止最常见漂移：工具代码悄悄变成业务逻辑。

避免返工的脚手架路径

生产项目建议按此顺序：

1. 使用官方脚手架创建
2. 选定一种模板（博客、营销站或作品集）
3. 除非与明确团队标准冲突，否则保留生成约定
4. 每次只加一处结构性定制

为何重要：多数上线延迟并非缺功能，而是早期结构分叉，日后破坏文档、脚本与上手体验。

推荐脚手架命令

# 脚手架创建新的 EmDash CMS 项目
npm create emdash@latest my-emdash-site
cd my-emdash-site

# 安装依赖并启动本地开发
npm install
npm run dev

常见反模式

1）未敲定内容模型就先写路由

在集合与分类形态未达成一致前搭建页面路由，会导致昂贵重写。

2）把部署关切塞进 UI 目录

不要把部署专用脚本与配置辅助放在 components 或 pages。平台关切放在配置文件与 src/lib。

3）无界的 utils 文件夹

若什么都进 utils，可发现性会崩。优先在 src/lib 用命名域，例如 src/lib/content、src/lib/media、src/lib/auth。

初始项目完成的定义

仅在以下检查全部通过时，才算脚手架完成：

• 本地开发服务器无需手工补丁即可运行
• 有一条示例内容端到端可走通
• 种子数据可在全新环境导入
• CI 构建通过，无环境专属 hack
• 新贡献者能在约十分钟内摸清仓库结构

接下来做什么

结构稳定后：

1. 在仓库中记录运行时选择与迁移标准
2. 在体量变大前定义内容类型命名约定
3. 为选定平台编写部署运行手册

目录结构是架构，不是装饰。尽早锁定可省数周。