前言¶
前端项目写完之后，往往还要经历一遍熟悉又琐碎的上线流程：登录托管平台、关联站点、确认构建命令和发布目录、先打预览再推生产。命令本身不复杂，但步骤多、容易漏，尤其在用 AI 编程助手帮你改代码时，助手如果对 Netlify CLI 的约定不熟，就容易卡在鉴权、站点未关联，或把预览部署和正式发布搞混。
netlify-deploy 正是为这类场景准备的 Agent Skill。它把「检查登录 → 关联或新建站点 → 安装依赖 → 预览/生产部署」固化成可复用的流程说明，让支持 Agent Skills 标准的工具（如 Cursor、Codex、Claude Code）在你提到部署、托管、发布到 Netlify 时，按同一套步骤执行，而不是临时拼命令。
这是什么¶
netlify-deploy 是 OpenAI 在 openai/skills 仓库 skills/.curated/ 目录下收录的一份 curated Skill，官方路径为：
https://github.com/openai/skills/tree/main/skills/.curated/netlify-deploy
它的定位很明确：通过 Netlify CLI（文档与示例统一使用 npx netlify，不必先全局安装）完成 Web 项目的部署、托管与发布，覆盖预览部署和生产部署。触发场景包括用户说「部署到 Netlify」「发布站点」「关联现有站点」等。
需要说明的是：该仓库 README 已提示整体 deprecated，后续 Codex 相关示例更推荐参考 openai/plugins；但截至本文写作时，netlify-deploy 的 SKILL.md 与配套 references/ 仍可从上述 curated 路径获取。Skill 基于通用的 SKILL.md 格式（可参见 Agent Skills 开放标准），因此同一份技能包可以放到不同 AI 编程工具对应的 skills 目录中使用。
核心功能与亮点¶
根据官方 SKILL.md，这个 Skill 主要自动化以下几件事：
-
校验 Netlify CLI 登录状态
先跑npx netlify status。未登录则引导执行npx netlify login（浏览器 OAuth）；也可以改用环境变量NETLIFY_AUTH_TOKEN（在 Netlify 用户设置里生成 Personal Access Token）。 -
识别项目是否已关联站点
从status输出判断当前目录是否已 link 到某个 Netlify site。已关联则直接进入部署；未关联则尝试按 Git remote 链接，或走新建流程。 -
关联已有站点或创建新站点
- 有 Git remote 时：npx netlify link --git-remote-url <REMOTE_URL>
- 链接失败或不存在站点：npx netlify init（选团队、站点名、构建配置，必要时生成netlify.toml） -
部署前检查依赖
对 npm 项目执行npm install；若检测到 yarn / pnpm 等，则使用对应安装命令。 -
区分预览与生产
- 已有站点、默认测试：npx netlify deploy（Draft/Preview，得到独立预览 URL）
- 新站点或明确要上线：npx netlify deploy --prod
CLI 会读取netlify.toml，或交互询问 build command / publish directory；Skill 也会尽量根据package.json推断框架默认值。 -
结果回报与排错指引
部署结束后应向用户回报 Deploy URL、生产站点 URL（若走了--prod）、控制台日志入口，并可提示netlify open。常见错误（未登录、未关联站点、构建失败、发布目录不存在）在 Skill 里都有对应处理建议。
Skill 目录里还附带按需加载的参考文档：references/cli-commands.md、references/deployment-patterns.md、references/netlify-toml.md，用来补充命令速查、场景决策树和配置说明，避免把所有细节塞进主 SKILL.md。
安装与启用¶
获取 Skill 文件¶
从官方目录获取 netlify-deploy 文件夹（至少包含 SKILL.md，建议一并保留 references/）：
# 克隆仓库后拷贝 curated 技能目录（任选一种获取方式）
git clone https://github.com/openai/skills.git
cp -r openai/skills/skills/.curated/netlify-deploy <你的-skills-目录>/netlify-deploy
在 Codex 中，也可按 openai/skills 文档使用内置安装器安装 curated 技能（安装后如未识别，需重启 Codex）：
$skill-installer netlify-deploy
放到各工具的 skills 目录¶
Agent Skills 是「一个目录 + 一份 SKILL.md」。不同工具扫描路径不同，可按官方文档放置（项目级或用户级均可）：
| 工具 | 常见项目级路径 | 常见用户级路径 |
|---|---|---|
| Cursor | .cursor/skills/netlify-deploy/ 或 .agents/skills/netlify-deploy/ |
~/.cursor/skills/、~/.agents/skills/ |
| Claude Code | .claude/skills/netlify-deploy/ |
~/.claude/skills/netlify-deploy/ |
| Codex | .agents/skills/netlify-deploy/ |
~/.agents/skills/ |
目录结构示意：
netlify-deploy/
├── SKILL.md
└── references/
├── cli-commands.md
├── deployment-patterns.md
└── netlify-toml.md
Cursor 文档还说明：为兼容性会额外加载 .claude/skills/、.codex/skills/ 等路径。跨工具协作时，优先使用 .agents/skills/ 往往更省事。
运行时前置条件¶
Skill 本身不替代 Netlify 账号与网络权限，使用前需满足：
- 本机可执行 Node.js 环境，以便
npx netlify ...（Netlify 官方 CLI 文档要求 Node.js 18.14.0 或更高；Skill 侧通过 npx 调用，不强制全局npm install -g netlify-cli） - 已登录 Netlify，或已设置
NETLIFY_AUTH_TOKEN - 当前目录是有效的 Web 项目
- 若沙箱拦截了出站网络，Skill 提示需用更高权限重试（文档中的
sandbox_permissions=require_escalated）；部署可能需要数分钟，注意超时设置
典型用法示例¶
下面流程来自官方 SKILL.md 的完整示例，可在本地或让 Agent 按步骤执行。
1. 鉴权¶
npx netlify status
# 若未登录：
npx netlify login
# 无浏览器环境时，可用 Token：
export NETLIFY_AUTH_TOKEN=your_token_here
Token 可在 https://app.netlify.com/user/applications#personal-access-tokens 生成。这与 Netlify 官方 CLI 文档中的鉴权方式一致。
2. 关联或初始化站点¶
git remote show origin
npx netlify link --git-remote-url https://github.com/user/repo
# 若站点尚不存在：
npx netlify init
3. 安装依赖并部署¶
npm install
# 先预览（Draft Deploy）
npx netlify deploy
# 确认无误后再上生产
npx netlify deploy --prod
4. 构建配置（netlify.toml）¶
若仓库根目录已有 netlify.toml，CLI 会自动使用。没有时，CLI 会询问构建命令与发布目录。Skill 给出的常见默认值示例包括：
- Next.js：
npm run build，发布目录.next - React（Vite）：
npm run build，发布目录dist - 纯静态 HTML：无需构建命令，发布当前目录
实际项目仍以本地构建产物目录为准。例如 Vite 也可显式指定目录：
npx netlify deploy --dir=dist --prod
部署模式选择上，Skill 的 decision tree 建议：新站点或首次上线倾向 --prod；已有站点改代码时先 deploy 预览，再 --prod。
5. 对 Agent 可以说的话¶
启用 Skill 后，不必背命令，直接描述意图即可，例如：
- 「把当前 Vite 项目部署到 Netlify，先出预览链接」
- 「用 Git remote 关联已有 Netlify 站点并做生产发布」
- 「这个仓库还没建过站点，帮我
netlify init再--prod」
Agent 应按 Skill 先查 status、处理登录与 link，再部署，而不是跳过鉴权直接 deploy。
适用场景与注意事项¶
比较适合：
- 个人或小团队的静态站、Vite/React、简单前端项目，希望「改完就能预览 URL」
- 用 AI 助手写页面时，把「上线」也交给同一会话闭环处理
- 需要统一团队部署话术与步骤（预览优先、密钥不进 Git、依赖先装好）
使用时注意：
- 先预览再生产：Skill 明确建议多数已有站点先跑无
--prod的deploy，确认预览 URL 后再正式发布。 - 密钥不要提交仓库：环境变量应放在 Netlify 控制台（Site Settings → Environment Variables）或用
npx netlify env:set，构建里通过process.env读取。 - 构建失败先本地复现：发布目录不存在、exit code 1 等，优先本地
npm run build核对输出目录与netlify.toml。 - 网络与沙箱：在受限沙箱里部署失败时，按 Skill 提示申请放宽网络权限后再试。
- 仓库状态：引用 openai/skills 时留意其 README 的 deprecated 说明；若你所在工具生态已迁移到 plugins 分发，以当前工具文档的安装方式为准，Skill 内容仍以
SKILL.md为准。 - 框架特例：不同框架在 Netlify 上的最佳构建配置可能随平台演进变化；Skill 中的默认值是引导建议，复杂项目（尤其 Next.js 等）应再对照 Netlify 框架文档 与 CLI 入门 核对。
部署完成后，可用 npx netlify open 打开控制台，若使用了 Netlify Functions，可用 npx netlify logs 查看函数日志；本地联调 Functions 可用 npx netlify dev。
小结¶
netlify-deploy 把 Netlify CLI 上线链路写成 Agent 可执行的标准流程：登录校验、站点关联、依赖安装、预览与生产分离，并附带命令与场景参考。对经常把前端 demo 推到 Netlify 的开发者来说，它补上的是「写完即上线」闭环里最容易被助手漏掉的那几步。
官方地址：https://github.com/openai/skills/tree/main/skills/.curated/netlify-deploy
Netlify CLI 文档：https://docs.netlify.com/cli/get-started/
netlify.toml 参考：https://docs.netlify.com/configure-builds/file-based-configuration/
