netlify-deploy

name	netlify-deploy
description	使用 Netlify CLI（`npx netlify`）把 web 项目部署到 Netlify。当用户要求在 Netlify 上部署、托管、发布或关联一个站点/仓库时使用，包括预览部署和生产部署。

Netlify 部署 Skill

使用 Netlify CLI 把 web 项目部署到 Netlify，并智能检测项目配置和部署场景。

概览

本 skill 通过以下方式自动化 Netlify 部署：

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

前置条件

• Netlify CLI：通过 npx 使用（无需全局安装）
• 认证：拥有有效登录会话的 Netlify 账户
• 项目：当前目录中有效的 web 项目
• 当沙箱阻止部署所需的网络调用时，用 network-enabled shell permissions 重试。
• 部署可能需要几分钟。使用合适的超时值。

认证模式

本 skill 采用预认证 Netlify CLI 的方式：

1. 用 npx netlify status 检查认证状态
2. 若未认证，引导用户完成 npx netlify login
3. 若认证无法建立，优雅失败

认证使用以下二者之一：

• 基于浏览器的 OAuth（首选）：netlify login 打开浏览器进行认证
• API Key（备选）：设置 NETLIFY_AUTH_TOKEN 环境变量

工作流程

1. 校验 Netlify CLI 认证

检查用户是否已登录 Netlify：

npx netlify status

预期输出模式：

• ✅ 已认证：显示已登录用户邮箱和站点关联状态
• ❌ 未认证："Not logged into any site" 或认证错误

若未认证，引导用户：

npx netlify login

这会打开一个浏览器窗口进行 OAuth 认证。等待用户完成登录，然后再次用 netlify status 校验。

备选：API Key 认证

如果无法进行浏览器认证，用户可以设置：

export NETLIFY_AUTH_TOKEN=your_token_here

Token 可在此生成：https://app.netlify.com/user/applications#personal-access-tokens

2. 检测站点关联状态

从 netlify status 输出判断：

• 已关联：站点已连接到 Netlify（显示站点名/URL）
• 未关联：需要关联或创建站点

3. 关联到已有站点或创建新站点

若已关联 → 跳到第 4 步

若未关联，尝试按 Git remote 关联：

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

# If Git-based, extract remote URL
# Format: https://github.com/username/repo or [e-mail]: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. 选择 team/账户
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. 报告结果

部署后，向用户报告：

• Deploy URL：本次部署的唯一 URL
• Site URL：生产 URL（如为生产部署）
• Deploy logs：Netlify 面板日志链接
• Next steps：建议用 netlify open 查看站点或面板

处理 netlify.toml

如果存在 netlify.toml 文件，CLI 会自动使用它。若不存在，CLI 会提示：

• Build command：如 npm run build、next build
• Publish directory：如 dist、build、.next

常见框架默认值：

• Next.js：build command npm run build，publish .next
• React (Vite)：build command npm run build，publish dist
• Static HTML：无 build command，publish 当前目录

如可能，本 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

错误处理

常见问题及解决办法：

"Not logged in" → 运行 npx netlify login

"No site linked" → 运行 npx netlify link 或 npx netlify init

"Build failed" → 检查 netlify.toml 或 CLI 提示中的 build command 和 publish directory → 校验依赖已安装 → 查看构建日志找具体错误

"Publish directory not found" → 校验 build command 成功运行 → 检查 publish directory 路径是否正确

疑难排查

提升网络访问权限

如果因网络问题（超时、DNS 错误、连接重置）部署失败，用提升的权限重跑部署（使用 network-enabled shell permissions）。当沙箱网络阻止出站请求时，部署需要提升的网络访问权限。

给用户的示例引导：

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 commands
• Deployment patterns
• netlify.toml guide