EmDash CMS 專案啟動與目錄結構
從空儲存庫開始新 EmDash 專案的實務架構指南，目錄配置可從概念驗證平滑擴展到生產環境。
本指南適用對象
當你從空儲存庫開始，且希望目錄結構能支援：
- 每日編輯內容變更
- 不破壞 CMS 假設的前台迭代
- 之後從本機開發遷移到 Cloudflare
請使用本指南。
目標不是做出最聰明的資料夾樹，而是降低長期維護成本。
先決定執行環境
在建立檔案前，先決定未來 30 到 90 天要優化哪種執行環境：
Node.js + SQLite：最快本機上手、營運複雜度最低Cloudflare Workers + D1 + R2：生產 SSR、受管儲存，與 EmDash 外掛模型整合較緊密
若團隊仍在驗證內容策略，先從 Node.js 開始，並從第一天起保留 Cloudflare 友善的命名。這可避免過早鎖定平台，又讓遷移路徑直觀。
建議的基準目錄結構
your-emdash-site/
├── src/
│ ├── components/ # Reusable UI pieces only
│ ├── layouts/ # Shared page shells
│ ├── pages/ # Astro routes
│ ├── lib/ # Domain logic and integrations
│ ├── styles/ # Global and shared style tokens
│ └── live.config.ts # Live content collection mapping
├── seed/ # Seed data for bootstrap/demo
├── public/ # Static assets (favicons, static images)
├── docs/ # Product docs and editorial content (MDX)
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── emdash-env.d.ts若現有專案已使用 utils/ 而非 lib/，暫時保留。僅在能落實清楚責任歸屬時再更名。
目錄責任歸屬
結構只有在責任明確時才有效：
src/components：僅呈現；不直接呼叫資料庫或儲存src/layouts：共用框架（head、導覽框、頁尾殼層）src/pages：路由組合與呈現用的資料接線src/lib：商業規則、資料轉接器與平台膠水程式seed：新環境可重現的基準內容
此分割可避免最常見的漂移：工具程式默默變成商業邏輯。
避免返工的啟動路徑
生產專案請依此順序：
- 以官方鷹架建立
- 選一種模板（blog、marketing 或 portfolio）
- 保留產生慣例，除非與明確團隊標準衝突
- 一次只加一種結構自訂
為何順序重要：多數上線延遲不是缺功能，而是早期結構分歧，日後破壞文件、腳本與上手流程。
建議的啟動指令
# Scaffold a new Emdash CMS project
npm create emdash@latest my-emdash-site
cd my-emdash-site
# Install and start local development
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。
初始專案設定的完成定義
僅當下列檢查皆通過，才視為啟動完成：
- 本機開發伺服器不需手動補丁即可執行
- 一條範例內容流程端到端可用
- 可在全新環境匯入 seed 資料
- CI 建置通過，無環境專屬 hack
- 新貢獻者能在十分鐘內理解儲存庫導覽
接下來做什麼
結構穩定後：
- 在儲存庫中記錄執行環境選擇與遷移準則
- 在內容量成長前定義內容類型命名慣例
- 為所選平台實作部署實務手冊
目錄結構是架構，不是門面。早點定錨可省下數週。