openai-netlify-deploy

Netlify 部署技能

使用 Netlify CLI 部署 Web 项目，并智能检测项目配置和部署上下文。

概述

此技能可自动执行 Netlify 部署：

• 验证 Netlify CLI 身份验证
• 检测项目配置和框架
• 关联现有站点或创建新站点
• 部署到生产或预览环境

前提条件

• Netlify CLI：通过 npx 安装（无需全局安装）
• 身份验证：拥有处于登录状态的 Netlify 账户
• 项目：当前目录中存在有效的 Web 项目
• 部署可能需要几分钟。请使用适当的超时值。

身份验证方式

此技能采用 预先通过身份验证的 Netlify CLI 方式：

1. 使用 npx netlify status 检查身份验证状态
2. 如果尚未通过身份验证，引导用户运行 npx netlify login
3. 如果无法完成身份验证，则妥善处理失败情况

身份验证可通过以下任一方式完成：

• 基于浏览器的 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 远程仓库进行关联：

# Check if project is Git-based
git remote show origin

# If Git-based, extract remote URL
# Format: https://github.com/username/repo or [email protected]:username/repo.git

# Try to link by Git remote
npx netlify link --git-remote-url <REMOTE_URL>

如果关联失败（Netlify 上不存在该站点）：

# Create new site interactively
npx netlify init

此流程会引导用户完成以下操作：

1. 选择团队／账户
2. 设置站点名称
3. 配置构建设置
4. 如有需要，创建 netlify.toml

4. 验证依赖项

部署前，确保已安装项目依赖项：

# For npm projects
npm install

# For other package managers, detect and use appropriate command
# yarn install, pnpm install, etc.

5. 部署到 Netlify

根据上下文选择部署类型：

预览／草稿部署（现有站点的默认选项）：

npx netlify deploy

这会创建一个带有唯一 URL 的部署预览，供测试使用。

生产部署（用于新站点或明确要求的生产部署）：

npx netlify deploy --prod

这会将项目部署到正式生产 URL。

部署流程：

1. CLI 检测构建设置（来自 netlify.toml 或通过提示询问用户）
2. 在本地构建项目
3. 将构建后的资源上传到 Netlify
4. 返回部署 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. Check authentication
npx netlify status

# If not authenticated:
npx netlify login

# 2. Link site (if needed)
# Try Git-based linking first
git remote show origin
npx netlify link --git-remote-url https://github.com/user/repo

# If no site exists, create new one:
npx netlify init

# 3. Install dependencies
npm install

# 4. Deploy (preview for testing)
npx netlify deploy

# 5. Deploy to production (when ready)
npx netlify deploy --prod

错误处理

常见问题及解决方案：

“未登录” → 运行 npx netlify login

“未关联站点” → 运行 npx netlify link 或 npx netlify init

“构建失败” → 检查 netlify.toml 或 CLI 提示中的构建命令和发布目录 → 确认已安装依赖项 → 查看构建日志中的具体错误

“未找到发布目录” → 确认构建命令已成功运行 → 检查发布目录路径是否正确

故障排除

提升网络访问权限

向用户提供的示例指导：

The deploy needs escalated network access to deploy to Netlify. I can rerun the command with escalated permissions—want me to proceed?

环境变量

用于密钥和配置：

1. 切勿将密钥提交到 Git
2. 在 Netlify 控制面板中设置：站点设置 → 环境变量
3. 在构建中通过 process.env.VARIABLE_NAME 访问

提示

• 先使用 netlify deploy（不加 --prod）进行测试，再部署到生产环境
• 运行 netlify open，在 Netlify 控制面板中查看站点
• 运行 netlify logs，查看函数日志（如果使用 Netlify Functions）
• 使用 netlify dev，在本地开发 Netlify Functions

参考

• Netlify CLI 文档：https://docs.netlify.com/cli/get-started/
• netlify.toml 参考：https://docs.netlify.com/configure-builds/file-based-configuration/

捆绑参考资料（按需加载）

• CLI 命令
• 部署模式
• netlify.toml 指南

适用场景

不适用场景