将 EmDash 添加到现有 Astro 项目

本指南将 EmDash 添加到 Astro 项目中，并通过一个已发布的条目验证集成。它使用 Node.js 适配器、SQLite 和本地媒体存储，使完整路径可以在一台机器上运行。

开始之前

使用 Astro 6 或更高版本以及 Node.js 22.16 或更高版本。在项目中检查两个版本：

node --version
npx astro --version

本指南将站点更改为 Astro 的 server 输出并配置 Node.js 适配器。这将改变站点的构建和部署方式。如果项目已经使用其他服务器适配器，不要添加第二个。保留该适配器并遵循其部署要求；对于 Cloudflare，使用 Cloudflare Workers 指南。

在更改配置之前，提交或以其他方式保存当前项目。

安装 EmDash

安装 EmDash、Node.js 适配器和 React 支持：
npm
```
npm install emdash @astrojs/node @astrojs/react react react-dom
```
pnpm
```
pnpm add emdash @astrojs/node @astrojs/react react react-dom
```
yarn
```
yarn add emdash @astrojs/node @astrojs/react react react-dom
```
即使公开站点没有 React 组件，EmDash 也会将 React 用于管理面板。

在 astro.config.mjs 中注册适配器、React 和 EmDash。如果文件已包含其他集成或设置，请保留它们并从此示例中添加相关条目：

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

export default defineConfig({
    output: "server",
    adapter: node({ mode: "standalone" }),
    integrations: [
        react(),
        emdash({
            database: sqlite({ url: "file:./data.db" }),
            storage: local({
                directory: "./uploads",
                baseUrl: "/_emdash/api/media/file",
            }),
        }),
    ],
});

SQLite 将内容和内容模型存储在 data.db 中。本地存储适配器将媒体写入 uploads/ 并通过 EmDash 的媒体路由提供服务。如果两个路径尚未排除，请将它们添加到 .gitignore。

创建 src/live.config.ts 以将 EmDash 连接到 Astro 的内容系统：
```
import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
    _emdash: defineLiveCollection({ loader: emdashLoader() }),
};
```
如果项目已有 src/live.config.ts，请将 _emdash 条目添加到导出的 collections 对象中，而不是替换文件。用于基于文件的集合的单独 src/content.config.ts 可继续并行工作。
生成本地加密密钥并写入 .env：
```
npx emdash secrets generate --write .env
```
确认 .env 被 .gitignore 排除。该密钥保护存储在数据库中的插件密钥。替换或丢失密钥会使这些加密值不可读，因此在部署站点之前请保留一份受保护的备份。

设置站点和内容

启动开发服务器：
```
npm run dev
```
打开 http://localhost:4321/_emdash/admin/。首次访问会重定向到设置向导。输入站点详情，创建管理员账户并注册通行密钥。

由于此项目没有种子文件，设置将应用 EmDash 的内置起始模型。它创建 Posts 和 Pages 集合、标题和内容字段，以及分类和标签分类法。不会添加示例条目。
打开 Posts，选择 New Post，输入 EmDash is connected 作为标题。选择 Save 创建条目，然后选择 Publish。

数据库现在在内置 posts 集合中包含一个已发布的条目。下一步从 Astro 页面读取它。

查询条目

创建一个服务器渲染的测试页面，列出已发布的文章：

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

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

if (error) {
	throw error;
}
---

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

打开 http://localhost:4321/emdash-test/。页面显示 EmDash is connected。如果你在管理面板中更改并重新发布标题，重新加载此页面将显示更新后的标题。

在本地开发期间，EmDash 还会从当前内容模型生成 emdash-env.d.ts。生成的声明为 TypeScript 提供 posts 集合名称及其 title 字段。不要手动编辑该生成文件。

如果验证失败

如果管理界面停留在 Loading EmDash…，请检查 Astro integrations 数组中是否包含 react()。仅安装 @astrojs/react 而不注册是不够的。
如果 getEmDashCollection() 返回有关实时集合的错误，请检查 src/live.config.ts 是否使用 emdashLoader() 导出 _emdash。
如果页面在开发中有效但部署的编辑不显示，请检查页面是否未预渲染，以及部署的应用程序是否使用服务器输出。
如果构建无法解析某个导入，请重新运行安装命令并确认五个包已添加到此项目而非其他工作区目录。

阅读配置了解其他数据库、存储适配器和身份验证选项。内容查询指南涵盖过滤器、分页、预览和缓存提示。