EmDash 站点配置指南：从 astro.config.mjs 到类型生成的完整工程实践

CMS后端前端插件系统【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址https://gitcode.com/gh_mirrors/emdas/emdash点击查看免费下载本篇指南以 EmDash 官方配置文档为骨架完整讲解一个 EmDash 站点的全部配置文件astro.config.mjs中的集成与存储/数据库适配器、反向代理与 TLS 终结场景下的siteUrl处理、live.config.ts内容集合注册、emdash-env.d.ts类型生成以及package.json依赖与开发服务器工作流。读完你可以照着配置一个可运行的 Node.js 或 Cloudflare 站点并理解每个配置项背后的实现原理。astro.config.mjs一切配置的入口EmDash 是一个基于 Astro 的集成式 CMS核心能力通过emdash()集成函数注入 Astro。该集成只在构建期运行其源码位于 packages/core/src/astro/index.ts入口导出emdash/astro模块同时导出local、s3存储适配器和memoryCache缓存适配器。Node.js本地开发与自托管最常见的开发形态是 Node.js 自托管用 SQLite 做数据库、本地文件系统做媒体存储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 }), image: { layout: constrained, responsiveStyles: true, }, integrations: [ react(), emdash({ database: sqlite({ url: file:./data.db }), storage: local({ directory: ./uploads, baseUrl: /_emdash/api/media/file, }), }), ], devToolbar: { enabled: false }, });关键点说明output: server与adapter: node({ mode: standalone })把站点构建为 Node 服务standalone模式生成独立的服务入口image.layout: constrained与image.responsiveStyles: true启用 Astro 图像优化与响应式样式emdash({ database: sqlite(...), storage: local(...) })分别指定数据库与媒体存储后端baseUrl指向媒体文件的服务路由/_emdash/api/media/filedevToolbar: { enabled: false }关闭 Astro 自带开发工具栏因为管理后台由 EmDash 在/_emdash/admin提供。存储适配器还支持 S3s3()缓存在emdash/astro中提供memoryCache()Cloudflare 环境下 R2 与 KV 适配器则来自emdash-cms/cloudflare见下文。反向代理与 TLS 终结siteUrl 的正确姿势当站点部署在 TLS 终结的反向代理nginx、Caddy、Traefik 等后面时应用内部看到的Astro.url是内网地址如http://localhost:4321而浏览器访问的是公网地址如https://mysite.example.com。这种不一致会破坏 passkeyWebAuthn、CSRF、OAuth 重定向、登录跳转等一系列依赖 origin 的功能。第一步声明允许的公网 Host。通过 Astro 的security.allowedDomains配置让 Astro 依据X-Forwarded-*请求头重建 URL开发模式下还需要在vite.server.allowedHosts中加入同样的域名否则 Vite 会拒绝代理传来的Host。第二步设置siteUrl。若重建后的 URL 仍与浏览器地址不一致TLS 终结场景常见直接在emdash()中声明公网 originemdash({ siteUrl: https://mysite.example.com, // ... });容器部署时更适合通过环境变量注入便于在构建期之外按环境配置EMDASH_SITE_URLhttps://mysite.example.com # or: SITE_URLhttps://mysite.example.comsiteUrl取代了早期的passkeyPublicOrigin它只能修 passkey如今统一作用于passkey、CSRF origin 校验、OAuth 重定向、登录后跳转、MCP 发现、快照导出、sitemap、robots.txt 以及 JSON-LD 结构化数据。从源码看siteUrl的解析优先级定义在 packages/core/src/api/public-url.ts 的getPublicOrigin先取config.siteUrl再回退到EMDASH_SITE_URL/SITE_URL环境变量运行时通过process.env读取容器部署时不会被 Vite 构建期静态替换掉最后回退到请求 URL 的 origin。因此无代理环境下即使不配置也能正常工作。配置项的类型定义与详尽注释位于 packages/core/src/astro/integration/runtime.ts其中还包含allowedOrigins当同一部署在多个共享父域名的 hostname 下可达如主站加 preview 子域时siteUrl定义rpIdallowedOrigins声明额外接受断言的 originWebAuthn 要求rpId是所有 origin 的可注册后缀并可与EMDASH_ALLOWED_ORIGINS环境变量合并。推荐的开发模式前置 TLS 终结时astro dev --host 127.0.0.1仅回环监听通常就足够——代理在本地访问 dev server而siteUrl与浏览器端的 HTTPS origin 保持一致无需把 Node 端口暴露到局域网。CloudflareD1 R2Cloudflare 形态下数据库使用 D1、媒体存储使用 R2适配器从emdash-cms/cloudflare导入import cloudflare from astrojs/cloudflare; import react from astrojs/react; import { d1, r2 } from emdash-cms/cloudflare; import { defineConfig } from astro/config; import emdash from emdash/astro; export default defineConfig({ output: server, adapter: cloudflare(), image: { layout: constrained, responsiveStyles: true, }, integrations: [ react(), emdash({ database: d1({ binding: DB, session: auto }), storage: r2({ binding: MEDIA }), }), ], devToolbar: { enabled: false }, });需要配套wrangler.jsonc声明 D1 与 R2 绑定{ name: my-site, compatibility_date: 2026-02-24, compatibility_flags: [nodejs_compat], assets: { directory: ./dist }, d1_databases: [ { binding: DB, database_name: my-site, }, ], r2_buckets: [ { binding: MEDIA, bucket_name: my-site-media, }, ], }d1({ session: auto })让 D1 会话管理由集成自动处理nodejs_compat兼容标志是 EmDash 运行时在 Workers 上工作的前提。仓库中真实的营销模板配置见 templates/marketing-cloudflare/wrangler.jsonc它还额外声明了每分钟的 cron 触发器供维护任务使用、可选的worker_loaders绑定沙箱插件需要 Workers 付费计划并把main指向 templates/marketing-cloudflare/src/worker.ts——该文件从emdash-cms/cloudflare/worker组合默认 handler、createScheduledHandler()与PluginBridge导出是 Cloudflare Worker 的固定骨架。插件注册第三方/本地插件在emdash()的plugins数组中注册import auditLog from emdash-cms/plugin-audit-log; emdash({ database: sqlite({ url: file:./data.db }), storage: local({ directory: ./uploads, baseUrl: /_emdash/api/media/file }), plugins: [auditLog], }),本地插件既可以直接传入包导出也可以用{ id, version, entrypoint }对象形式。营销模板中的示例templates/marketing-cloudflare/astro.config.mjs展示了本地插件的一种坑entrypoint 必须使用绝对file://URLnew URL(..., import.meta.url).href因为虚拟模块emdash/plugins没有磁盘位置可锚定相对路径。同一配置里还演示了通过astro-iconset的include只打包模板实际引用的 Phosphor 图标避免给 Worker 产物增加数 MB 体积。live.config.ts注册 EmDash 内容集合每个 EmDash 站点都需要在src/live.config.ts放置这个固定样板文件import { defineLiveCollection } from astro:content; import { emdashLoader } from emdash/runtime; export const collections { _emdash: defineLiveCollection({ loader: emdashLoader() }), };它把 EmDash 的 live 内容集合注册进 Astro 内容层。所有内容类型都通过唯一的_emdash集合对外服务查询具体类型时使用getEmDashCollection(posts)、getEmDashEntry()等 API见 templates/marketing-cloudflare/src/live.config.ts 中的注释说明。emdash-env.d.ts 与类型生成emdash-env.d.ts由开发服务器启动时自动生成在项目根目录为你的内容集合提供 TypeScript 类型也是tsconfig.json引入的类型来源。生成结果形如/// reference typesemdash/locals / import type { PortableTextBlock } from emdash; export interface Post { id: string; slug: string | null; status: string; title: string; featured_image?: { id: string; src?: string; alt?: string; width?: number; height?: number; }; content?: PortableTextBlock[]; excerpt?: string; createdAt: Date; updatedAt: Date; publishedAt: Date | null; } declare module emdash { interface EmDashCollections { posts: Post; } }注意字段类型由你的内容 schema 决定。营销模板中的实际生成文件只包含pages集合因为 templates/marketing-cloudflare/seed/seed.json 只定义了一个pages集合且没有featured_image字段而是多了bylines?: ContentBylineCredit[]署名信用。以当前仓库的 templates/marketing-cloudflare/emdash-env.d.ts 为基准即可。schema 变更后dev server 会在启动时自动重新生成此文件也可以随时手动触发。手动生成类型emdash types命令从运行中的站点拉取 schema 并生成类型# 本地开发服务器在项目根目录写 emdash-env.d.ts npx emdash types # 远程实例 npx emdash types --url https://my-site.pages.dev # 自定义输出路径 npx emdash types --output src/types/cms.ts其实现位于 packages/core/src/cli/commands/types.ts通过--url/连接参数创建客户端拉取 schema 与 TS 类型写入--output指定路径默认.emdash/types.ts同时把原始 schema 以.emdash/schema.json落盘供工具链使用并打印集合数量与 schema 版本。dev server 侧的自动生成逻辑在 packages/core/src/astro/integration/dev-typegen.tsschema 的 JSON 接口由/_emdash/api/schema路由packages/core/src/astro/routes/api/schema/index.ts提供——这正是--url远程模式抓取的端点。package.json依赖清单Node.js 站点所需的关键依赖{ dependencies: { astro: ^6.0.0, emdash: workspace:*, astrojs/node: ^9.0.0, astrojs/react: ^4.0.0, react: ^18.0.0, react-dom: ^18.0.0 } }Cloudflare 形态则把astrojs/node换成astrojs/cloudflare并额外加入emdash-cms/cloudflare提供d1、r2、worker入口devDependencies 中增加wrangler与cloudflare/workers-types。仓库中真实的 Cloudflare 模板依赖清单见 templates/marketing-cloudflare/package.json其中emdash与emdash-cms/cloudflare使用workspace:*指向本地仓库包其余通过 pnpmcatalog:统一版本模板还在emdash字段里声明了seed: seed/seed.json把种子数据与 package.json 绑定。开发服务器迁移、种子数据与初始化pnpm dev # 启动 Astro 开发服务器 npx emdash types # 从运行中的站点刷新类型EmDash 运行时在首次请求时自动执行待处理的数据库迁移当数据库为空且尚未完成 setup 时会应用内置种子数据模板场景下即上述seed.json定义的内容集合、菜单与页面内容营销模板以marketing.*块类型预置了首页、定价页与联系页。Astro 集成在服务器启动时生成emdash-env.d.ts。管理后台位于http://localhost:4321/_emdash/admin。首次运行会进入 setup 向导创建管理员账号之后即可开始创作内容。小结一个 EmDash 站点本质上就是一份 Astro 配置加三份固定文件astro.config.mjs声明数据库、存储、插件与公网 originsrc/live.config.ts注册内容集合emdash-env.d.ts由工具链自动维护。反向代理部署记得配置security.allowedDomains与siteUrl或EMDASH_SITE_URL环境变量Cloudflare 部署则要保证wrangler.jsonc中的 D1/R2 绑定与集成参数一一对应。遵循以上配置即可获得一个带管理后台、类型安全查询、自动迁移与种子数据的完整 CMS 站点。赞分享CMS后端前端插件系统【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址https://gitcode.com/gh_mirrors/emdas/emdash点击查看免费下载相关推荐EmDash 站点配置完全指南从 astro.config.mjs 到类型生成EmDash 站点配置完全指南从 astro.config.mjs 到类型生成 本篇指南以 EmDash 官方 starter cloudflare 模板自带CMS后端前端插件系统EmDash 站点配置完全指南从 astro.config.mjs 到类型生成EmDash 站点配置完全指南从 astro.config.mjs 到类型生成 EmDash 是基于 Astro 构建的全栈 TypeScript CMS站CMS后端前端插件系统EmDash CMS 站点配置完全指南从 astro.config.mjs 到类型生成EmDash CMS 站点配置完全指南从 astro.config.mjs 到类型生成 本篇指南围绕 EmDash基于 Astro 的全栈 TypeScriCMS后端前端插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考