netlify-deploy

Netlify 部署 Skill

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

概述

此 Skill 可自动执行 Netlify 部署：

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

前提条件

• Netlify CLI：通过 npx 安装（无需全局安装）
• 身份验证：拥有活跃登录会话的 Netlify 账户
• 项目：当前目录中包含有效的 Web 项目
• 当沙盒阻止部署网络调用时，使用 sandbox_permissions=require_escalated 重新运行。
• 部署可能需要几分钟。请使用合适的超时值。

身份验证模式

此 Skill 使用 预先完成身份验证的 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

预期输出模式：

• ✅ 已完成身份验证：显示已登录用户的电子邮件和站点关联状态
• ❌ 尚未完成身份验证：“Not logged into any site” 或身份验证错误

如果尚未完成身份验证，请引导用户：

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：无需构建命令，发布当前目录

如果可能，Skill 应根据 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 提示中的构建命令和发布目录 → 确认依赖项已安装 → 查看构建日志，查找具体错误

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

故障排除

提升网络访问权限

如果部署因网络问题（超时、DNS 错误、连接重置）失败，请使用提升后的权限重新运行部署（设置 sandbox_permissions=require_escalated）。当沙盒网络阻止外发请求时，部署需要提升网络访问权限。

给用户的示例说明：

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 控制面板中设置：Site Settings → Environment Variables
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 指南