HeyForm 开源表单构建器完整指南三步从本地跑通到自托管部署【免费下载链接】heyformOpen-Source Form Builder项目地址: https://gitcode.com/GitHub_Trending/he/heyformHeyForm 是一个可以部署在自己服务器上的开源表单构建器Form Builder。适合想把问卷、报名、反馈收集放到自己网站、数据存进自己数据库的小微企业和开发者。它内置 20 多种题型组件、条件逻辑、品牌主题、漏斗分析、CSV 导出与 Webhook、Zapier 集成全部以 AGPL-3.0 协议开源。这篇文章带你在本地三步跑起来再按场景讲透每个能力遇到问题去哪看。第一次运行环境要求与三步跑通路径硬门槛只有一条Node.js ≥ 20 且 pnpm ≥ 8在根目录 package.json 的 engines 字段声明除此之外服务端运行还需要一个 MongoDB 和一个 Redis先在本机把它们起好。第一步安装克隆仓库一条命令装完所有依赖。git clone https://gitcode.com/GitHub_Trending/he/heyform cd heyform pnpm install这是一个 pnpm monorepopackages/下有 server、webapp、form-renderer 等七个子包装一次全部就位。第二步组装配好服务端启动所需的环境变量。完整清单在 packages/server/src/environments/index.ts最基础的五项MONGO_URImongodb://127.0.0.1:27017/heyform REDIS_HOST127.0.0.1 APP_LISTEN_PORT9157 SESSION_KEY换成你的长随机字符串 FORM_ENCRYPTION_KEY换成你的长随机字符串SESSION_KEY 用于登录会话签名FORM_ENCRYPTION_KEY 用于加密表单敏感字段两者务必替换。第三步运行pnpm dev根目录的 dev 脚本会并行拉起 webapp 和 server看到服务就绪后浏览器打开 http://localhost:9157 即可进入。跑通后先进工作区建一张表单走一遍“搭建 → 发布 → 填写 → 查提交”的完整闭环再对照下一节按场景看功能。能力讲解按场景看表单构建器的五件事搭建任意问卷20 多种题型组件痛点真实问卷不只是“一个文本框加提交”电话、日期、文件、签名都可能出现。做法每种题型是一个独立 block集中在 packages/form-renderer/src/blocks/覆盖短文本、邮箱、电话、数字、日期与日期范围、地址、国家、图片选择、文件上传、评分、意见量表、签名、输入表格、法律条款、支付等。同一套组件也负责用户填写时的渲染界面内置中、英、日、德等 12 种语言见 packages/form-renderer/src/locales/。用条件逻辑让表单“动起来”痛点用户上一题答“否”下一题就该消失有人答完还要直接跳到不同链接。做法HeyForm 支持条件逻辑与 URL 重定向——根据前面的回答控制后续题目的显示隐藏或在提交后跳转指定链接。前端判定在 packages/answer-utils/src/validate-condition.ts服务端保存逻辑的入口在 packages/server/src/resolver/form/update-form-logics.resolver.ts。品牌主题与四种嵌入方式痛点表单是网站门面颜色、字体、布局要贴合品牌还要能放页面里、弹窗里或做成整页。做法主题定制覆盖字体、颜色、背景并支持自定义 CSS 做更深改造实现见 packages/form-renderer/src/theme.ts。表单还带官方嵌入 JS 库 packages/embed/src/提供标准 iframe、模态框、弹出层、整页四种模式用法示例在 packages/embed/example/index.html。提交分析、CSV 导出与邮件通知痛点数据收上来却看不见、带不走等于白做。做法分析面板提供流失率、完成率等指标页面代码在 packages/webapp/src/pages/form/Analytics/提交记录可一键导出 CSV入口在 packages/server/src/controller/export-submissions.controller.ts文件生成逻辑在 packages/server/src/service/export-file.service.ts每收到一条新提交可触发邮件通知队列实现在 packages/server/src/queue/submission-notification.queue.ts。对接外部系统Webhook 与 Zapier、Make痛点表单提交后数据要自动流进 CRM、表格或其他内部系统。做法服务端提供 Webhook 端点 packages/server/src/apps/webhook.ts并支持与统计、营销平台以及 Zapier、Make.com 等工具集成集成配置与执行在 packages/server/src/service/integration.service.ts异步执行走 packages/server/src/queue/integration-queue.ts。上线前先回答三个高频顾虑顾虑一怕垃圾提交刷爆数据库做法三层防线都是现成的——配置 GOOGLE_RECAPTCHA_KEY 与 SECRET 开启人机验证填 AKISMET_KEY 启用 Akismet 垃圾内容检测内置一次性邮箱域名清单直接拦截临时邮箱注册见 packages/server/src/utils/disposable-email.ts 与 packages/server/src/utils/anti-bot/。还可以再设表单密码与 IP 提交限制见 packages/server/src/resolver/endpoint/form-password.resolver.ts。效果机器脚本、一次性邮箱、IP 刷量各有一道墙。顾虑二能不能只允许自己人注册做法设 APP_DISABLE_REGISTRATIONtrue 关闭公开注册此后访客只能凭工作区邀请链接开户服务端会校验邀请码存在、有效且未过期才放行完整流程写在 docs/invite-only-registration.md。效果可以当内部收集工具开出去外部人员无法自行注册。顾虑三数据安全吗做法表单敏感字段用 FORM_ENCRYPTION_KEY 加密存储会话签名依赖 SESSION_KEY项目留有安全加固与漏洞公告的完整记录见 docs/security-hardening-2026-08-06.md 和 docs/security-advisory-ghsa-fg7j-rmgr-rc9g.mdAGPL-3.0 开源也意味着代码持续接受社区审查。效果密钥、流程、协议三样可查自托管后数据不出自己的机器。踩坑清单⚠️Node 版本偏低根 package.json 声明 node 20、pnpm 8先node -v和pnpm -v确认不满足时安装与启动会直接报错。环境变量缺失没有 MONGO_URI、SESSION_KEY、FORM_ENCRYPTION_KEY 时服务起不来对照 packages/server/src/environments/index.ts 逐项补齐。忘起 MongoDB 和 Redis服务端两者都依赖先本地启动或参考根目录 docker-compose.test.yml 的既有配置。对外访问没配 APP_HOMEPAGE_URL默认按 0.0.0.0:9157 拼装首页地址会影响 Cookie 域与 CORS 白名单用域名访问时请显式指定。上传目录不可写表单文件上传写入 packages/server/static/upload部署时确保目录存在且有写权限见 Dockerfile 中的 mkdir。误读协议AGPL-3.0 要求修改后对外提供服务的版本也需开源商用分发前先读 README 的 License 一节。落地第一步收尾起步就一条命令pnpm dev前提是完成上面三步的依赖与环境配置。建议按这个顺序读源码packages/server/src/controller/form.controller.ts——表单相关的 HTTP 入口先看服务端怎么被调用packages/webapp/src/pages/form/——构建器、渲染、提交、分析等页面实现packages/form-renderer/src/blocks/——每种题型组件的具体写法packages/embed/example/index.html——嵌入 JS 库在真实页面里的用法packages/server/test/——大量安全与行为测试读它最懂设计意图。接下来做三件事本地跑起来建一张五题表单发布亲自填完一遍。配好 SMTP 相关变量用一条真实提交验证邮件通知与 CSV 导出。对照 Dockerfile 与 docker-compose.test.yml把服务以 9157 端口部署到自己的服务器上。【免费下载链接】heyformOpen-Source Form Builder项目地址: https://gitcode.com/GitHub_Trending/he/heyform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考