建立你的第一個 EmDash 站點 | EmDash CMS Everything

本教學從 Starter 範本建立 Node.js 站點。結果使用 SQLite 與本機媒體儲存，因此你可以在沒有雲端帳戶的情況下完成本教學。

若你已有 Astro 站點，請改為遵循將 EmDash 新增到現有 Astro 專案。

前置條件

安裝 Node.js 22.16 或更高版本以及 npm。繼續前檢查已安裝的 Node.js 版本：

node --version

該命令必須報告 v22.16.0 或更高版本。

搭建站點

啟動互動式鷹架：
npm
```
npm create emdash@latest
```
pnpm
```
pnpm create emdash@latest
```
yarn
```
yarn create emdash
```
bun
```
bun create emdash@latest
```
出現提示時選擇以下選項：
- Project name: my-emdash-site
- Where will you deploy? Node.js
- Which template? Starter
- Which package manager? 保留步驟 1 中命令偵測到的套件管理器。
- Install dependencies? Yes
這些選擇會建立帶有 Posts 與 Pages 的通用 Node.js 站點。鷹架還會將產生的 EMDASH_ENCRYPTION_KEY 寫入被 gitignore 的 .env 檔案。

若依賴安裝失敗，專案檔案仍會保留。繼續前請執行鷹架列印的重試命令。
進入專案目錄並啟動開發伺服器：
npm
```
cd my-emdash-site
npm run dev
```
pnpm
```
cd my-emdash-site
pnpm dev
```
yarn
```
cd my-emdash-site
yarn dev
```
bun
```
cd my-emdash-site
bun dev
```
保持此終端機開啟。Astro 會列印本機站點 URL，通常為 http://localhost:4321/。

完成設定

開啟 http://localhost:4321/_emdash/admin/。新站點會重新導向到設定精靈。

輸入 Site Title 與可選的 Tagline。保持選取 Include sample content，以便教學從範本的 Welcome 文章與 About 頁面開始，然後選擇 Continue。
輸入 Your Email 與可選的 Your Name，然後選擇 Continue。
當瀏覽器開啟憑證提示時註冊通行金鑰。註冊後選擇 Open the dashboard。

儀表板開啟，導覽中有 Posts 與 Pages。設定精靈已將 Starter 範本的內容模型與範例內容套用到本機 SQLite 資料庫。

發布一次編輯

開啟 Posts，然後開啟 Welcome。
將標題改為 Hello from EmDash，然後選擇 Save。
選擇 Publish changes，使已儲存的草稿成為向訪客顯示的版本。
在另一個分頁開啟 http://localhost:4321/。首頁會列出 Hello from EmDash。

當 Astro 轉譯首頁時，Starter 範本會呼叫 getEmDashCollection("posts")。重新載入頁面會在執行階段從 EmDash 讀取已發布版本。

產生的站點如何運作

鷹架會產生一個普通的 Astro 專案，EmDash 在三處連接。

astro.config.mjs 啟用伺服器轉譯與 Node.js 配接器。它還為管理面板註冊 React，並為 EmDash 提供 SQLite 資料庫與上傳媒體的目錄。 src/live.config.ts 檔案將該基於資料庫的內容連接到 Astro 的 Live Content Collections。

首頁隨後查詢 posts 集合。其查詢等價於產生頁面的以下部分：

---
import { getEmDashCollection } from "emdash";

const { entries: posts, cacheHint } = await getEmDashCollection("posts", {
	orderBy: { published_at: "desc" },
});

if (Astro.cache?.enabled) Astro.cache.set(cacheHint);
---

<ul>
	{posts.map((post) => <li>{post.data.title}</li>)}
</ul>

seed/seed.json 定義 Posts 與 Pages 集合、它們的欄位，以及設定精靈套用的範例內容。在本機開發期間，EmDash 讀取該模型並重新整理 emdash-env.d.ts，以便你的編輯器可以檢查查詢程式碼中的集合名稱與欄位。

產生的 .env 在執行階段提供加密金鑰。它與儲存模型與內容的 SQLite 檔案是分開的。

下一步

閱讀架構了解這些部分如何協同運作。要將 EmDash 新增到已有站點，請遵循將 EmDash 新增到現有 Astro 專案。查詢內容指南涵蓋篩選、分頁、草稿與錯誤處理。當站點準備好離開你的機器時，將其部署到 Cloudflare Workers 或 Node.js。媒體庫指南說明上傳、媒體欄位、取代與刪除。