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 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 远程地址进行关联：

# 检查项目是否基于 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

根据提示引导用户完成：

1. 选择团队/账号
2. 设置站点名称
3. 配置构建参数
4. 需要时生成 netlify.toml

4. 检查项目依赖

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

# npm 项目
npm install

# 对于其它包管理器，自动识别并运行对应命令
# 如 yarn install, pnpm install 等

5. 部署到 Netlify

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

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

npx netlify deploy

生成具备独立 URL 的部署预览，便于测试验证。

生产环境部署（用于新站点或明确指定发布到生产环境）：

npx netlify deploy --prod

直接部署到线上生产环境地址。

部署执行流程：

1. CLI 自动识别构建设置（读取 netlify.toml 或交互式询问）
2. 在本地完成项目构建
3. 将构建产物上传至 Netlify
4. 返回部署链接

6. 输出部署结果

部署完成后，向用户汇报：

• 部署预览地址 (Deploy URL)：本次部署的专属测试链接
• 生产环境地址 (Site URL)：线上正式地址（若为生产部署）
• 部署日志 (Deploy logs)：指向 Netlify 控制台日志页面的链接
• 后续建议：建议用户运行 netlify open 查看站点或控制台

处理 netlify.toml

若项目根目录下存在 netlify.toml，CLI 将自动加载该配置。若不存在，CLI 会提示输入：

• 构建命令 (Build command)：例如 npm run build、next build
• 发布目录 (Publish directory)：例如 dist、build、.next

常见框架默认值：

• Next.js：构建命令 npm run build，发布目录 .next
• React (Vite)：构建命令 npm run build，发布目录 dist
• 静态 HTML：无需构建命令，发布目录为当前目录

Skill 应优先从 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

常见错误与排查

常见问题及解决方案：

"Not logged in"（未登录）
→ 运行 npx netlify login

"No site linked"（未关联站点）
→ 运行 npx netlify link 或 npx netlify init

"Build failed"（构建失败）
→ 检查 netlify.toml 或 CLI 交互提示中的构建命令与发布目录设置
→ 确认项目依赖已正常安装
→ 查看构建日志获取具体报错信息

"Publish directory not found"（未找到发布目录）
→ 确认构建命令已成功执行
→ 检查发布目录路径是否填写正确

疑难解答

网络提权访问

如果部署因网络问题失败（超时、DNS 错误、连接重置等），请带上提权权限重新运行部署（设置 sandbox_permissions=require_escalated）。当沙盒网络环境拦截了出站请求时，部署需要提权网络访问权限。

给用户的提示示例：

部署到 Netlify 需要提权网络访问权限。我可以带上提权权限重新运行该命令，是否继续？

环境变量配置

关于密钥与敏感配置：

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 配置指南