Ghost Signup Form 深入指南在任意网站嵌入会员注册表单的开发、测试与发布全流程【免费下载链接】GhostIndependent technology for modern publishing, memberships, subscriptions and newsletters.项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost导读Signup Form全称 tryghost/signup-form是 Ghost 仓库中一个独立的可嵌入公共应用public app它产出一段可在任意第三方站点通过script标签加载的 UMD 脚本让站长在不引入整套 Portal 的情况下也能在任意位置植入一个对接 Ghost 会员体系Members的邮箱注册表单。本文以 apps/signup-form/README.md 为骨架结合 apps/signup-form 包内源码讲清楚该组件的嵌入机制与配置参数、monorepo 内三种开发/调试模式的区别、验收测试矩阵以及从自动 Patch 到手动 Minor/Major 的发布路径。一、模块定位一个能嵌进任何网站的注册表单Signup Form 是 Ghost Monorepo 中众多 public appPortal、Comments UI、Signup Form、Sodo Search、Announcement Bar、Admin Toolbar 等之一。它的产出物不是传统意义上的页面而是一个可通过任意script async标签引入的 UMD 构建包名定义在 apps/signup-form/package.json{ name: tryghost/signup-form, version: 0.3.34, description: Embeddable signup form for Ghost sites, files: [LICENSE, README.md, umd/], type: module }files字段说明发布到 npm 的核心产物是umd/目录即打包后的umd/signup-form.min.js。构建入口在 vite.config.mts 中被指定为src/index.tsx。一个典型的嵌入写法取自 preview.html 演示页如下div styleheight: 40vmin; min-height: 360px; script srchttp://localhost:2368/ghost/assets/signup-form/signup-form.min.js >export function isMinimal(options: SignupFormOptions): boolean { return !options.title; }也就是说只要不传data-title就渲染 Minimal 形态——不含标题/图标/背景只保留邮箱输入框 订阅按钮高度可压到约 58px适合塞进页脚、侧边栏等紧凑区域preview.html 的 Minimal 示例即此形态。传入data-title则渲染带图标、标题、描述的完整居中卡片。两种形态对应 src/components/frame.tsx 中的两套 iframe 尺寸策略MinimalResizableFrameiframe 高度跟随内容高度通过ResizeObserver监听iframeRoot.scrollHeight实时设置在页面上像一段内联 DOM完整卡片FullHeightFrame额外用ResizeObserver监听 script 标签父容器让 iframe 与宿主编排保持同步同时设置position: absolute避免影响宿主布局。所有表单内容都渲染在一个srcDoc!DOCTYPE html的 iframe 内见 src/components/iframe.tsxCSS 以?inline内联进 iframe 的head相当于一个简易 Shadow DOM从而彻底隔离宿主页面的全局样式污染。iframe 还会把内部的keydown事件转发到主窗口保证无障碍与快捷键行为不受隔离影响。外层 iframe 默认display: block; width: 100%; height: 0避免内联元素常见的高度抖动。2.4 提交链路integrity-token 与 Magic Link表单只有一个状态机FormPage → SuccessPage页面注册逻辑收敛在 src/components/pagesform-page.tsx 先调用isValidEmailsrc/utils/validator.tsx做本地校验非法时提示 Please enter a valid email address不发起请求随后按 src/utils/api.tsx 的实现依次调用两个 members 接口POST /members/api/send-magic-link/ Body: { email, emailType: signup, labels, urlHistory, integrityToken }其中integrityToken先通过GET /members/api/integrity-token/获取请求头固定携带app-pragma: no-cache与x-ghost-version用于防止邮件订阅接口被滥用。urlHistory承担会员归因追踪当表单嵌入在 Ghost 站点自身域名上时复用与 Portal 相同的sessionStorage[ghost-history]归因数据当嵌入在外部第三方站点时则构造一条referrerMedium: Embed的历史记录见 src/utils/helpers.tsx这样通过外站表单注册的会员也能在 Ghost 后台看到正确的来源归因。Minimal 模式下成功后不跳转页面而是让按钮原地切换为Email sent成功态完整卡片模式则通过 src/pages.tsx 的 Page 注册表切换到 SuccessPage显示已提交的邮箱地址。三、开发环境搭建3.1 前置条件在 Ghost Monorepo 根目录先安装依赖并初始化工作区pnpm setup随后克隆仓库如需git clone https://gitcode.com/GitHub_Trending/gh/Ghost仓库采用 pnpm workspace Nx 管理根 package.json 中通过pnpm nx run ghost-monorepo:docker:dev:public调度所有跨包脚本请用pnpm而非npm/yarn执行。3.2 三种开发模式的本质区别Signup Form 提供三条互不相同的开发命令容易混淆逐一说明命令位置行为是否监听端口pnpm dev:publicmonorepo 根目录启动标准开发环境Docker compose并开启所有 public-app 的 watch 任务是开发网关 Ghostpnpm dev:standaloneapps/signup-form内用 Vite 起独立 demo 服务器带 HMR是localhost:6173pnpm devapps/signup-form内仅执行vite build --watch --mode development增量产出 UMD否3.3 通过 monorepo 根目录跑整套 Ghost推荐在仓库根目录执行pnpm dev:public对应根 package.json 中的docker:dev:publicNx target。从依赖关系可以看到它做了三件事docker:up先把 compose.dev 全家桶Ghost、Caddy 等拉起来构建 Ghost 的静态资源build:assets同时启动 6 个 public-app 的devwatch target——admin、portal、comments-ui、signup-form、sodo-search、announcement-bar、admin-toolbar。因此它会同时启动标准开发环境 Signup Form watcher。由于 UMD 属于静态资源它不需要绑定自己的端口而是由开发网关Caddy统一托管。当你跑pnpm dev:public后可以在浏览器直接访问http://localhost:2368/ghost/assets/signup-form/signup-form.min.js页面里的script src就指向这个地址。3.4 独立 demo 服务器不依赖 Ghost 也能写 UI想在仅改动 Signup Form 自身样式时获得 Vite HMR 体验可以进入包目录cd apps/signup-form pnpm dev:standalone脚本在 apps/signup-form/package.json 中定义为vite --port 6173demo 首页地址为 http://localhost:6173。注意区分pnpm devvite build --watch --mode development只构建并 watchumd/signup-form.min.js不绑定任何端口源码级改动在 HMR 上不如 standalone 即时但其产物会被 3.3 节所述的 Caddy 直接伺服。3.5 联调完整表单standalone dev:public 双开由于 Vite 的 dev server 以ESM 模块提供源码以便 HMR而 ESM 加载时document.currentScript不可用它仅在经典脚本中有效开发模式只能退而求其次在 src/index.tsx 中若找不到document.currentScript且处于import.meta.env.DEV就改取页面里第一个未标记data-usedtrue的 script 标签作为注入锚点。这种 hack 只适合开发期生产行为并不等价。想验证与线上一致的生产行为需同时保持两个进程monorepo 根目录运行pnpm dev:public提供 Ghost UMD包目录运行pnpm dev:standalone然后打开http://localhost:6173/preview.htmlpreview.html 里每个 demo 区块加载的都是来自开发网关的真实 UMDhttp://localhost:2368/ghost/assets/signup-form/signup-form.min.js页面顶部还提供 Development build / Production build 切换导航。页面文案提示当提交表单报错时可把本地.env.development复制为.env.development.local并修改其中对应的 site urldemo 页中的%VITE_SITE_URL%由 Vite 环境变量替换。preview 页内置了 5 类典型的验收场景可作为集成自测清单场景特征Full signup form完整卡片 图标 标题 描述 背景色Without icon完整卡片但不带data-iconMinimal不传data-title仅单行输入框Invalid configurationdata-sitehttps://invalid/提交时必然报错用于验证错误提示Translated传data-localenl-BE验证 i18n四、测试ESLint 与 Playwright 验收矩阵在apps/signup-form目录内pnpm lint # 运行 ESLint针对 src 与 test pnpm test:acceptance # Chromium 上的 Playwright 验收测试headless pnpm test:acceptance:slowmo # 有头模式 放慢播放PLAYWRIGHT_SLOWMO100 pnpm test:acceptance:full # 在全部配置浏览器上运行从 apps/signup-form/package.json 的脚本与 playwright.config.ts 可以看到底层细节验收脚本预设NODE_OPTIONS--experimental-specifier-resolutionnode --no-warnings与VITE_TESTtrueslowmo 变体追加TIMEOUT100000、PLAYWRIGHT_SLOWMO100并--headedtest:acceptance:full通过ALL_BROWSERS1让 playwright 在Chromium Firefox WebKit三套 project 上运行默认只跑 ChromiumCI 环境下并发 worker 数设为 100% 全核并行失败自动重试 2 次测试自身通过webServer拉起pnpm dev:test先vite build再用vite preview --port 6175并轮询http://localhost:6175/signup-form.min.js就绪后再开始用例。测试源码位于 apps/signup-form/test其中 e2e 用例与上面提到的data-testid如input、button、error-message、wrapper一一对应便于在 form-view.tsx 等组件中反查选择器。五、发布流程自动 Patch 与手动 Minor/Major5.1 Patch 发布全自动Signup Form 的 patch 版本发布是零人工干预的Signup Form 的改动合并到main后CI 自动发布下一个patch版本到 npm并清除 jsDelivr CDN 缓存所有固定在该 major/minor 版本线上的站点会自动吃到该 patch无需等待一次完整的 Ghost 发版。这条补丁直达机制让表单的紧急修复样式、i18n、接口容错能以远快于 Ghost 月度发版的节奏触达所有嵌入站点。5.2 Minor / Major 发布需人工触发有意的 minor 或 major 版本升级遵循双版本一致原则因为这类升级通常会引入新参数或破坏性行为需要跟随正式的 Ghost 发版一起默认上线。步骤为从干净的 branch 执行pnpm ship选择 minor 或 major 版本号将生成的 release commit 合并到main等待一次 public Ghost release把新版本线设为站点默认。关键点在于pnpm ship会同时更新两处——包自身的版本号apps/signup-form/package.json 中的version字段以及 Ghost 的默认 Signup Form 版本号。ship前会先跑pnpm lintpreship钩子发布前置钩子prepublishOnly会执行一次pnpm build确保发布到 npm 的包始终包含最新构建产物。六、常见问题速查表单没有渲染出来确认脚本是经典script src...且非 moduleESM 下document.currentScript为 null生产包会直接抛出[Signup Form] Cannot find current script tag。Minimal 还是完整卡片一切取决于有没有data-title——isMinimal()只判断这一个条件。表单提交后跳转失败/报 400检查data-site是否指向正确的 Ghost 站点该地址会被拼接为${site}/members/api/send-magic-link/演示页里https://invalid/即用于验证这条错误路径。多个表单出现在同一页面每个script会自动携带自己的挂载 divgh-signup-root不同表单请使用不同的 script 标签与data-label-*无需任何额外初始化。版权说明Copyright (c) 2013-2026 Ghost FoundationSignup Form 以 MIT license 开源仓库根目录LICENSE为完整协议文本。【免费下载链接】GhostIndependent technology for modern publishing, memberships, subscriptions and newsletters.项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考