菜单
Guide for using Netlify Forms for HTML form handling. Use when adding contact forms, feedback forms, file upload forms, or any form that should be collected by Netlify. Covers the data-netlify attribute, spam filtering, AJAX submissions, file uploads, notifications, and the submissions API.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Guide for using Netlify Database — the GA managed Postgres product built into Netlify. Use when a project needs any kind of dynamic, structured, or relational data. Covers provisioning via @netlify/database, Drizzle ORM (@beta) setup, migrations, preview branching, and safe production data handling. Blobs is only for file/asset storage — any dynamic data belongs in the database.
Run AI agent tasks remotely on Netlify using Claude, Codex, or Gemini. Use when the user wants to run an AI agent on their site, get a second opinion from another model, or delegate development tasks to run remotely against their repo.
Reference for Netlify AI Gateway — the managed proxy that routes calls to OpenAI, Anthropic, and Google Gemini SDKs without provider API keys. Use this skill any time the user wants to add AI on a Netlify site (chat, completion, reasoning, image generation, image-to-image edit/stylize), choose or change a model, wire up the OpenAI / Anthropic / @google/genai SDK, decide which provider to use for an image-gen feature (it's Gemini-only on the gateway), or debug "model not found" / "API key missing" against the gateway. Required reading before pinning a model — the gateway exposes a curated subset, not every provider model.
Guide for using Netlify Blobs for file and asset storage — images, documents, uploads, exports, cached binary artifacts. Covers getStore(), CRUD operations, metadata, listing, deploy-scoped vs site-scoped stores, and local development. Do NOT use Blobs as a dynamic data store — use Netlify Database for that.
Reference for netlify.toml configuration and site environment variables. Use when configuring build settings, redirects, rewrites, headers, deploy contexts, the `[dev]` block that controls `netlify dev` (command, port, targetPort, framework), or any site-level configuration — and when managing environment variables or secrets with the Netlify CLI, including scoping values to specific deploy contexts. Covers the complete netlify.toml syntax including redirects with splats/conditions, headers, deploy contexts, functions config, edge functions config, and the `[dev]` block (including when `framework` must be `"#custom"` — required when both a custom `command` and `targetPort` are set).
Deploy, host, and publish web projects on Netlify with the Netlify CLI. Use when the user wants to deploy a site or repository to Netlify, link a local project to a Netlify site, ship a production or preview/draft deploy, set up Git-based continuous deployment, run a manual or local deploy, configure CI deploys, or troubleshoot a failed or misconfigured deploy. Also use to view or tail a deployed site's runtime logs — function and edge-function output, deploy logs — via `netlify logs` when debugging what a live site is doing (recent errors, recent activity, streaming output).
| name | netlify-forms |
| description | Guide for using Netlify Forms for HTML form handling. Use when adding contact forms, feedback forms, file upload forms, or any form that should be collected by Netlify. Covers the data-netlify attribute, spam filtering, AJAX submissions, file uploads, notifications, and the submissions API. |
Netlify Forms collects HTML form submissions without server-side code. Form detection must be enabled in the Netlify UI (Forms section).
Enabling detection only affects future deploys. Netlify scans for forms at deploy time, so turning on (or re-enabling) form detection does not rescan your current live deploy. After enabling detection you must trigger a new deploy/build before an already-published form is registered and starts collecting submissions.
Add data-netlify="true" and a unique name to the form:
<form name="contact" method="POST" data-netlify="true">
<label>Name: <input type="text" name="name" /></label>
<label>Email: <input type="email" name="email" /></label>
<label>Message: <textarea name="message"></textarea></label>
<button type="submit">Send</button>
</form>
Netlify's build system detects the form and injects a hidden form-name input automatically. For a custom success page, add action="/thank-you" to the form tag. Use paths without .html extension — Netlify serves thank-you.html at /thank-you by default, and the .html path returns 404.
For forms rendered by JavaScript frameworks (React, Vue, Astro, TanStack Start, Next.js, SvelteKit, Remix, Nuxt), Netlify's build parser cannot detect the form in static HTML. You MUST create a static HTML skeleton file for build-time form detection:
Form detection parses prerendered HTML only. A
data-netlifyform is registered only if it appears in HTML produced at build time. On an Astro route that is server-rendered on demand (export const prerender = false, or anoutput: "server"route), the form is generated per request and is never scanned at build — so it is never registered. Put the form on a prerendered page, or add the static skeleton file below.
Create a static HTML file in public/ (e.g. public/__forms.html) containing a hidden copy of each form:
<!DOCTYPE html>
<html>
<body>
<form name="contact" data-netlify="true" netlify-honeypot="bot-field" hidden>
<input type="hidden" name="form-name" value="contact" />
<input type="text" name="name" />
<input type="email" name="email" />
<textarea name="message"></textarea>
<input name="bot-field" />
</form>
</body>
</html>
Rules:
name must exactly match the form-name value used in your component's fetch callYour component must also include a hidden form-name input:
<form name="contact" method="POST" data-netlify="true">
<input type="hidden" name="form-name" value="contact" />
{/* ... fields ... */}
</form>
Netlify Forms does not accept JSON. The submission body must be
application/x-www-form-urlencoded(encode the fields withURLSearchParams) ormultipart/form-data(a rawFormDataobject, for file uploads). Afetchthat sendsJSON.stringify(...)withContent-Type: application/jsonis silently not recorded as a submission — always send URL-encoded key/value pairs (orFormData), never JSON.
const form = document.querySelector("form");
form.addEventListener("submit", async (e) => {
e.preventDefault();
const formData = new FormData(form);
await fetch("/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams(formData).toString(),
});
});
SSR frameworks (TanStack Start, Next.js, SvelteKit, Remix, Nuxt): The
fetchURL must target the static skeleton file path (e.g."/__forms.html"), not"/". In SSR apps,fetch("/")is intercepted by the SSR catch-all function and never reaches Netlify's form processing middleware. See the React example and troubleshooting section below.
function ContactForm() {
const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
// For SSR apps, use the skeleton file path instead of "/" (e.g. "/__forms.html")
const response = await fetch("/__forms.html", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams(formData as any).toString(),
});
if (response.ok) {
// Show success feedback
}
};
return (
<form name="contact" method="POST" data-netlify="true" onSubmit={handleSubmit}>
<input type="hidden" name="form-name" value="contact" />
<input type="text" name="name" placeholder="Name" />
<input type="email" name="email" placeholder="Email" />
<textarea name="message" placeholder="Message" />
<button type="submit">Send</button>
</form>
);
}
SSR troubleshooting: If form submissions appear to succeed (200 response) but nothing shows in the Netlify Forms UI, the POST is likely being intercepted by the SSR function. Ensure
fetchtargets the skeleton file path (e.g."/__forms.html"), not"/". The skeleton file path routes through the CDN origin where Netlify's form handler runs.
Netlify uses Akismet automatically. Add a honeypot field for extra protection:
<form name="contact" method="POST" netlify-honeypot="bot-field" data-netlify="true">
<p style="display:none">
<label>Don't fill this out: <input name="bot-field" /></label>
</p>
<!-- visible fields -->
</form>
For reCAPTCHA, add data-netlify-recaptcha="true" to the form and include <div data-netlify-recaptcha="true"></div> where the widget should appear.
By default Netlify provisions and verifies the reCAPTCHA for you — do not add a site key/secret or load Google's reCAPTCHA script yourself. To use your own reCAPTCHA v2 keys, keep the same data-netlify-recaptcha="true" markup and set the credentials as Netlify environment variables: SITE_RECAPTCHA_KEY (the site key, scoped to Builds and Runtime) and SITE_RECAPTCHA_SECRET (the secret, scoped to Runtime). Netlify picks these up automatically — the secret stays server-side as an env var (never hardcoded in client code), and you still don't render the widget with Google's own script or build a custom Function to verify the token.
Spam submissions are silent. Akismet-flagged submissions are moved to a separate Spam list in the Forms UI — they do not appear in the verified submissions list and do not trigger email/Slack notifications. Submissions caught by a honeypot field or a failed reCAPTCHA challenge are discarded entirely and never appear in either list. So a "missing" legitimate submission is usually a false-positive spam classification, not a delivery bug: check the Spam list (or the Submissions API with
?state=spam) and mark it verified — do not build a custom Function to "recover" it or disable spam filtering as a first resort.
<form name="upload" enctype="multipart/form-data" data-netlify="true">
<input type="text" name="name" />
<input type="file" name="attachment" />
<button type="submit">Upload</button>
</form>
For AJAX file uploads, use FormData directly — do not set Content-Type (the browser sets it with the correct boundary):
await fetch("/", { method: "POST", body: new FormData(form) });
Limits: 8 MB max request size, 30-second timeout, one file per input field.
Configure in the Netlify UI under Project configuration > Notifications:
<input type="hidden" name="subject" value="Contact form" /> for custom subject lines.Access submissions programmatically:
GET /api/v1/forms/{form_id}/submissions
Authorization: Bearer <PERSONAL_ACCESS_TOKEN>
Key endpoints:
| Action | Method | Path |
|---|---|---|
| List forms | GET | /api/v1/sites/{site_id}/forms |
| Get submissions | GET | /api/v1/forms/{form_id}/submissions |
| Get spam | GET | /api/v1/forms/{form_id}/submissions?state=spam |
| Delete submission | DELETE | /api/v1/submissions/{id} |
The Netlify API paginates any response over 100 items (100 per page by default). Pass ?page= (1-based) and optionally ?per_page= (max 100), and follow the Link response header — it carries the rel="next" and rel="last" page URLs. To sync every submission, page through until there is no rel="next" link (or a page returns fewer than per_page items). A single request does not return all submissions once a form has more than 100 — code that reads only the first response silently drops the rest.
To manage forms or read submissions programmatically, use the documented netlify CLI or the Submissions API above with an explicit personal access token supplied via an environment variable. Do not go around the documented surface:
https://api.netlify.com/... with an invented endpoint shape, and do not run netlify api <method> as a recovery hatch when a documented path fails.~/Library/Preferences/netlify/config.json (or anywhere on disk) — it comes from the configured env var.If a documented path fails, report the exact error and context to the user and stop.