name: netlify-deploy
description: 使用Netlify CLI (npx netlify)将Web项目部署到Netlify。当用户请求在Netlify上部署、托管、发布或链接网站/仓库时使用，包括预览和生产部署。
author: openai
Netlify部署技能
使用Netlify CLI自动化部署Web项目，智能检测项目配置和部署上下文。
概述
此技能通过以下方式自动化Netlify部署：
- 验证Netlify CLI认证状态
- 检测项目配置和框架
- 链接到现有站点或创建新站点
- 部署到生产或预览环境
先决条件
- Netlify CLI：通过npx安装（无需全局安装）
- 认证：Netlify账户处于活跃登录状态
- 项目：当前目录中有效的Web项目
- 当沙盒环境阻止部署网络调用时，使用
sandbox_permissions=require_escalated重新运行。 - 部署可能需要几分钟。使用适当的超时值。
认证模式
技能使用预认证的Netlify CLI方法：
- 使用
npx netlify status检查认证状态 - 如果未认证，引导用户通过
npx netlify login登录 - 如果无法建立认证，优雅失败
认证使用：
- 基于浏览器的OAuth（主要）：
netlify login打开浏览器进行认证 - API密钥（替代）：设置
NETLIFY_AUTH_TOKEN环境变量
工作流程
1. 验证Netlify CLI认证
检查用户是否登录到Netlify：
npx netlify status
预期输出模式：
- ✅ 已认证：显示登录用户邮箱和站点链接状态
- ❌ 未认证：显示“未登录到任何站点”或认证错误
如果未认证，引导用户：
npx netlify login
这将打开浏览器窗口进行OAuth认证。等待用户完成登录，然后再次使用netlify status验证。
替代方案：API密钥认证
如果浏览器认证不可用，用户可以设置：
export NETLIFY_AUTH_TOKEN=your_token_here
令牌可以在以下位置生成：https://app.netlify.com/user/applications#personal-access-tokens
2. 检测站点链接状态
从netlify status输出中确定：
- 已链接：站点已连接到Netlify（显示站点名称/URL）
- 未链接：需要链接或创建站点
3. 链接到现有站点或创建新站点
如果已链接 → 跳到步骤4
如果未链接，尝试通过Git远程链接：
# 检查项目是否基于Git
git remote show origin
# 如果基于Git，提取远程URL
# 格式：https://github.com/username/repo 或 git@github.com:username/repo.git
# 尝试通过Git远程链接
npx netlify link --git-remote-url <REMOTE_URL>
如果链接失败（站点在Netlify上不存在）：
# 交互式创建新站点
npx netlify init
这引导用户：
- 选择团队/账户
- 设置站点名称
- 配置构建设置
- 如果需要，创建netlify.toml
4. 验证依赖项
在部署前，确保项目依赖项已安装：
# 对于npm项目
npm install
# 对于其他包管理器，检测并使用适当命令
# yarn install, pnpm install, 等。
5. 部署到Netlify
基于上下文选择部署类型：
预览/草稿部署（现有站点的默认）：
npx netlify deploy
这创建一个部署预览，带有用于测试的唯一URL。
生产部署（对于新站点或明确的生产部署）：
npx netlify deploy --prod
这部署到实时生产URL。
部署过程：
- CLI检测构建设置（来自netlify.toml或提示用户）
- 本地构建项目
- 上传构建资产到Netlify
- 返回部署URL
6. 报告结果
部署后，向用户报告：
- 部署URL：此部署的唯一URL
- 站点URL：生产URL（如果生产部署）
- 部署日志：Netlify仪表板日志链接
- 后续步骤：建议
netlify open查看站点或仪表板
处理netlify.toml
如果存在netlify.toml文件，CLI自动使用它。如果没有，CLI将提示：
- 构建命令：例如，
npm run build,next build - 发布目录：例如，
dist,build,.next
常见框架默认：
- Next.js：构建命令
npm run build，发布.next - React (Vite)：构建命令
npm run build，发布dist - 静态HTML：无构建命令，发布当前目录
技能应尽可能从package.json检测框架并建议适当设置。
完整工作流程示例
# 1. 检查认证
npx netlify status
# 如果未认证：
npx netlify login
# 2. 链接站点（如果需要）
# 首先尝试基于Git链接
git remote show origin
npx netlify link --git-remote-url https://github.com/user/repo
# 如果无站点存在，创建新站点：
npx netlify init
# 3. 安装依赖项
npm install
# 4. 部署（测试预览）
npx netlify deploy
# 5. 部署到生产（当准备就绪时）
npx netlify deploy --prod
错误处理
常见问题和解决方案：
“未登录”
→ 运行npx netlify login
“无站点链接”
→ 运行npx netlify link或npx netlify init
“构建失败” → 检查netlify.toml或CLI提示中的构建命令和发布目录 → 验证依赖项已安装 → 查看构建日志获取具体错误
“发布目录未找到” → 验证构建命令是否成功运行 → 检查发布目录路径是否正确
故障排除
提升网络访问
如果部署因网络问题（超时、DNS错误、连接重置）失败，使用提升权限重新运行部署（使用sandbox_permissions=require_escalated）。当沙盒网络阻止出站请求时，部署需要提升网络访问。
向用户指导示例：
部署需要提升网络访问以部署到Netlify。我可以使用提升权限重新运行命令——要我继续吗？
环境变量
对于秘密和配置：
- 永远不要将秘密提交到Git
- 在Netlify仪表板中设置：站点设置 → 环境变量
- 在构建中通过
process.env.VARIABLE_NAME访问
提示
- 首先使用
netlify deploy（无--prod）测试再部署到生产 - 运行
netlify open在Netlify仪表板查看站点 - 运行
netlify logs查看函数日志（如果使用Netlify函数） - 使用
netlify dev进行本地开发与Netlify函数
参考
- Netlify CLI文档：https://docs.netlify.com/cli/get-started/
- netlify.toml参考：https://docs.netlify.com/configure-builds/file-based-configuration/