netlify-functions

netlify-functions 技能概览

netlify-functions 是用来做什么的

netlify-functions 是一项实用技能，专门用于按当前 Netlify 模式编写 Netlify serverless functions，而不是通用的 API 模板。它最适合那些需要在 Netlify 应用里交付后端端点、定时任务、后台工作或路由处理器，并希望借助 netlify-functions 技能减少结构、语法和部署适配方面猜测的人。

适合谁使用

如果你正在实现 netlify-functions for Backend Development，并且希望获得一份了解仓库结构的 Netlify 函数约定指南，就该使用这项技能。它尤其适合你已经知道自己要什么功能，但还不确定怎么组织文件、选什么路径，或如何用现代的 default export + Config 风格来写函数的时候。

它为什么值得纳入安装决策

netlify-functions 的核心价值在于，它聚焦的是安装阶段和实现阶段那些会直接影响函数能否在 Netlify 上真正跑起来的细节：文件放置、路由、TypeScript 形态、方法处理、流式传输，以及后台或定时行为支持。相比只会说“创建一个端点”的浅层提示，这种能力显然更有用。

如何使用 netlify-functions 技能

安装并验证这项技能

先通过你的 skills manager 执行 netlify-functions install 流程，然后确认仓库路径位于 skills/netlify-functions。快速检查时，先打开 SKILL.md，核对其作用范围是否和你的目标一致：函数位于 netlify/functions/、使用现代语法，以及包含 Netlify 专有配置。如果你的项目使用的是别的 serverless 平台，这项技能大概率不合适。

把目标改写成可执行提示词

有效的 netlify-functions usage 一定从具体目标开始，而不是一句空泛要求。高质量输入类似：“Create a Netlify function at /api/invoices/:id that reads an invoice ID, validates a Bearer token, and returns JSON in TypeScript.” 低质量输入则像：“Build an API.”
把路由、方法、数据源、鉴权规则和返回格式都写清楚，技能才能生成既符合 Netlify 运行时、又符合你应用契约的代码。

先读对文件

先看 SKILL.md，再检查仓库里任何链接到的相关部分，重点是现代语法、文件结构、路径路由、后台函数、定时函数、流式处理和方法路由。实践中，最关键的安装线索来自代码示例和约束：函数放在哪里、是否必须使用 Config、以及 Request/Response 应该怎么处理。
如果你的项目同时有 TypeScript 和 JavaScript，要特别留意扩展名优先级和命名冲突。

按 Netlify 的工作流来用

更稳妥的流程是：先定义端点，再选择 netlify/functions/ 下的文件路径，用 config.path 映射公开路径，然后实现 handler，并在部署前先本地测试返回结果。
如果你需要一个函数同时服务多个路由或方法，一开始就要在提示词里说明，这样技能才能选对路由模式，而不是只按单一路径做过拟合。

netlify-functions 技能常见问题

netlify-functions 只适合简单 API 路由吗？

不是。netlify-functions 还覆盖后台处理、定时执行、流式响应和方法路由。
如果你只需要一个很小的一次性端点，通用提示词可能已经够用；但一旦路由或运行时细节变得重要，这项技能就会更有价值。

使用前必须先了解 Netlify 吗？

不需要，但你必须有明确目标。只要能说清楚想要的路由、输入和输出，初学者也可以用这项技能。真正的阻力通常不是代码复杂度，而是你没有说清函数要如何映射到 Netlify 的文件和配置模型。

什么时候不该用这项技能？

如果你要在别的 serverless 平台上搭后端，需要长生命周期的服务器进程，或者想要不依赖 Netlify 约定的通用 Node.js 模式，那就不要用 netlify-functions。如果你的项目不能采用 netlify/functions/ 这种目录结构，它也不适合。

它和普通提示词有什么不同？

普通提示词也许能产出可运行代码，但 netlify-functions 更适合你需要可安装、且贴合仓库的指导时使用。它会把你引向 Netlify 的文件结构、现代 handler 签名和路由配置，因为这些才决定代码能不能真正部署。

如何改进 netlify-functions 技能

给出真正重要的约束

最有价值的输入是路由、方法、运行时、数据源、鉴权和输出格式。比如，“POST /api/webhooks/stripe, verify signature, return 200 fast, enqueue background work” 就比 “write a webhook” 好得多。这样能帮助 netlify-functions 选对结构，而不是自己补假设。

避开最常见的失败模式

最常见的错误是沿用旧版 handler 模式、把文件放错目录，或者根本没有定义路由。另一个常见问题是请求生成代码时，没有说明函数应该是静态的、带参数的，还是多路由的。
如果你想获得更好的 netlify-functions usage，就应该在第一次请求里把这些决策明确写出来。

从适合仓库的输出继续迭代

拿到第一版后，检查生成的函数是否符合你项目的扩展名、路径和部署模型。如果不符合，就用你想要的精确文件名、预期 URL，以及任何 Netlify 专属行为来细化提示词，比如定时执行或流式传输。通常，这种反馈闭环比单纯要求“更好一点的版本”但不给新约束，效果要好得多。