netlify-forms

netlify-forms 技能概览

netlify-forms 是用来做什么的

netlify-forms 技能可以帮你实现 Netlify Forms 的 HTML 表单处理，而不需要自己搭建服务端提交接口。它最适合联系表单、线索收集、反馈表单、简单文件上传，以及其他希望由 Netlify 统一收集和分发的表单场景。

适合谁使用

如果你是在 Netlify 上开发，并且希望为静态站点、SSR 应用或 JavaScript 渲染的表单找到一条清晰的配置路径，就适合使用这个 netlify-forms 技能。它尤其适合 Backend Development 工作流：目标是在不自建表单基础设施的前提下，仍然让提交稳定可靠。

实战中最重要的点

真正决定成败的，主要是表单是否能被正确识别、表单命名是否准确，以及你的表单是服务端渲染还是只在浏览器里出现。这个技能最有价值的地方，在于它能让你把 netlify-forms 的安装和使用步骤在首次部署时就做对，而不是靠反复试错。

如何使用 netlify-forms 技能

安装并限定技能作用范围

在你的 skills 工作流里使用 netlify-forms install 路径，然后先阅读 SKILL.md。这个仓库体积很小，而且是自包含的，所以 SKILL.md 是主要信息源；这里没有 rules/、references/ 或 resources/ 这些辅助目录可供查阅。

把目标说清楚，才能得到有用的提示词

给这个技能一个明确的表单目标、框架和部署上下文。好的输入像是：“为 Next.js 应用添加一个 Netlify 联系表单，带自定义感谢页和反垃圾保护。” 不好的输入像是：“设置表单。” 你把路由、字段列表和框架说得越具体，输出里需要猜的内容就越少。

先读会影响输出质量的部分

先看 Basic Setup 和 JavaScript-Rendered Forms，如果你需要非默认行为，再继续看 AJAX Submissions 和 Vanilla JavaScript。如果你的应用使用 React、Vue、SvelteKit、Remix、Nuxt 或 Next.js，那么构建时检测的说明就是 netlify-forms 指南里最关键的部分。

正确应用这套工作流

确保表单包含唯一的 name、method="POST" 和 data-netlify="true"。如果你需要自定义成功页，使用 /thank-you 这样的路径，不要写成 /thank-you.html。对于 JavaScript 渲染的表单，要提供一个用于构建时检测的静态 HTML 骨架；否则即使表单在界面里能看到，Netlify 也可能根本识别不到它。

netlify-forms 技能 FAQ

这比一个通用提示词更好吗？

是的，尤其当你需要生产环境真正重要的实现细节时：Netlify 如何识别表单、隐藏的 form-name 机制怎么工作，以及 JavaScript 渲染应用会有哪些不同。通用提示词经常会漏掉“能否被检测到”这个约束，而这正是 netlify-forms 最常见的落地障碍。

简单的 HTML 表单也需要这个技能吗？

如果你只是在 Netlify 上做一个基础联系表单，这个技能仍然能通过最小有效标记和成功页规则帮你省时间。如果你的需求已经超出 Netlify 托管范围，或者需要自定义后端逻辑，那 netlify-forms 可能就不是合适的方案。

它支持现代框架吗？

支持，但不能只依赖浏览器最终渲染出来的标记。对于 React、Vue、SSR 框架以及其他客户端渲染方案，这个技能之所以重要，就是因为它解释了 Netlify 构建检测所需的静态骨架模式。

对初学者友好吗？

大体上是友好的。语法本身并不复杂，但关键在于理解部署模型。初学者通常只要严格按 netlify-forms 的使用步骤来做，并避免默认认为“浏览器里看得到的表单”就一定会被自动识别，就能更快成功。

如何改进 netlify-forms 技能

补全缺失的部署信息

最好的结果通常来自一开始就把框架、托管方式和提交去向说清楚。请明确你是否需要 AJAX 提交、文件上传、垃圾信息过滤，或者自定义感谢页路由，这样技能才能选对实现路径。

描述表单的精确结构

把字段、校验需求，以及任何想要一起收集的隐藏元数据列出来。比如，“name、email、company、message，email 为必填，文件上传为可选”就比“联系表单”更有操作性，因为它能让技能生成更好的标记和更清晰的 Netlify 专属指导。

注意常见失败模式

最常见的错误包括漏写 data-netlify="true"、使用重复的表单名、忘记为 JavaScript 渲染表单提供静态检测骨架，以及成功页路径写错。如果第一次输出失败，先检查这些点，再去重写整个表单流程。

用构建和提交证据继续迭代

第一次生成后，先测试部署，检查表单是否出现在 Netlify 中，并记录缺失字段或路由问题。然后把具体失败现象补进 netlify-forms 提示词里，比如“生产环境里表单未被识别”或“本地 AJAX 提交正常，但部署后失败”，这样下一次输出才会更有针对性。