快速开始

本指南将引导你创建第一个 EmDash 站点，从安装到发布你的第一篇文章。

前提条件

• Node.js v22.12.0 或更高版本（不支持奇数版本号）
• npm、pnpm 或 yarn
• 代码编辑器（推荐 VS Code）

创建新项目

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

按照提示为项目命名并设置你的偏好选项。

启动开发服务器

完成设置向导

首次访问管理面板时，EmDash 的设置向导会引导你完成初始配置：

通行密钥注册完成后，你将登录并被重定向到管理仪表盘。

你的第一篇文章

项目结构

你的 EmDash 项目遵循标准的 Astro 结构，并增加了一些额外内容：

my-emdash-site/
├── astro.config.mjs      # Astro + EmDash 配置
├── src/
│   ├── live.config.ts    # 实时集合配置
│   ├── pages/
│   │   ├── index.astro   # 首页
│   │   └── posts/
│   │       └── [...slug].astro  # 动态文章页面
│   ├── layouts/
│   │   └── Base.astro    # 基础布局
│   └── components/       # 你的 Astro 组件
├── .emdash/
│   ├── seed.json         # 模板种子文件
│   └── types.ts          # 生成的 TypeScript 类型
└── package.json

配置文件

astro.config.mjs

以下配置将 EmDash 注册为 Astro 集成，使用本地 SQLite 数据库和本地文件存储：

import { defineConfig } from "astro/config";
import react from "@astrojs/react";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	integrations: [
		react(), // 必需 — 管理界面是一个 React 应用
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

src/live.config.ts

以下文件通过单个实时集合将 EmDash 连接到 Astro 的内容系统：

import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
	_emdash: defineLiveCollection({ loader: emdashLoader() }),
};

环境变量

在生产环境中，使用以下命令生成用于插件密钥加密的密钥：

npx emdash secrets generate

将生成的值作为 EMDASH_ENCRYPTION_KEY 添加到你的环境变量中，如下所示。此密钥用于加密存储插件密钥。现在就设置好，这样当插件密钥加密功能启用时，你的部署就已准备就绪。

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

密钥不会存储在数据库中——数据库中只存储加密后的密文。请将密钥备份到可靠的地方，因为丢失密钥意味着丢失所有用它加密的密钥数据。

预览 HMAC 密钥和评论者 IP 哈希盐会在首次使用时自动生成并存储在数据库中，因此你无需手动设置。只有在其他进程需要验证与你主站相同的令牌时，才需要覆盖预览密钥，如下所示。

EMDASH_PREVIEW_SECRET=your-preview-secret

在页面中查询内容

在 Astro 页面中使用 EmDash 的查询函数。这些函数遵循 Astro 的实时集合模式，集合查询返回 { entries, error }，单条目查询返回 { entry, error }：

---
import { getEmDashCollection } from "emdash";
import Base from "../layouts/Base.astro";

const { entries: posts } = await getEmDashCollection("posts");
---

<Base title="Home">
  <h1>Latest Posts</h1>
  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/posts/${post.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

以下页面通过 slug 获取单个条目：

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

const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);

if (!post) {
  return Astro.redirect("/404");
}
---

<h1>{post.data.title}</h1>

生成 TypeScript 类型

为获得完整的类型安全，从数据库模式生成类型：

npx emdash types

这会在 .emdash/types.ts 中创建所有集合的接口。你的编辑器将能够自动补全字段名称并捕获类型错误。

下一步

站点运行起来后，以下页面涵盖了接下来可以做的事情：

• 核心概念 — 了解 EmDash 的底层工作原理
• 内容管理 — 学习查询和渲染内容
• 媒体库 — 上传和管理图片及文件
• 创建博客 — 构建带分类和标签的完整博客
• 部署到 Cloudflare — 将你的站点部署到生产环境