netlify-deploy

Netlify 部署技能

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

概览

此技能可自动执行 Netlify 部署，具体包括：

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

先决条件

• Netlify CLI：通过 npx 安装（无需全局安装）
• 身份验证：拥有 Netlify 账户且当前已登录
• 项目：当前目录中包含有效的 Web 项目
• 如果沙盒限制了部署所需的网络调用，请使用 network-enabled shell permissions 重新运行。
• 部署可能需要几分钟。请使用合适的超时值。

身份验证方式

此技能使用 预先完成身份验证的 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 提示中的构建命令和发布目录 → 确认已安装依赖项 → 查看构建日志以查找具体错误

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

故障排查

提升网络访问权限

如果部署因网络问题（超时、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 控制面板中设置：站点设置 → 环境变量
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 指南