企业官网建设流程全解析

netlify-deploy 技能实战指南：基于 Netlify CLI 完成 Web 项目部署、站点链接与生产发布

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本指南围绕 skills 仓库中 netlify-deploy 技能 展开，它是一套面向 Codex 等 AI Agent 的 Netlify 部署技能：通过npx netlify调用 Netlify CLI，智能检测项目配置与框架类型，自动完成认证校验、站点链接、预览部署与生产发布。读完本文，你将掌握该技能的完整执行流程、每一步的命令语义与预期输出，并能结合仓库提供的 CLI 命令速查、部署模式参考 与 netlify.toml 配置参考，在真实项目中复现整套部署链路。

技能是什么：定位与触发条件

netlify-deploy 是仓库skills/.curated/netlify-deploy目录下的一个精选（curated）技能，其 SKILL.md 的 frontmatter 明确定义了它的职责：

• 名称：netlify-deploy
• 描述：使用 Netlify CLI（npx netlify）将 Web 项目部署到 Netlify；当用户要求 deploy、host、publish 或 link 站点/仓库到 Netlify（含预览部署与生产部署）时使用。

配套的 agents/openai.yaml 给出了技能对外暴露的接口信息：显示名 "Netlify Deploy"、简介 "Deploy web projects to Netlify with the Netlify CLI"，并提供一个可直接使用的默认提示词：

Deploy this project to Netlify and return the preview URL, build settings, and any required fixes.

技能目录遵循"指令 + 参考素材"的组织方式：主指令文件SKILL.md定义完整工作流；references/下三份参考文档作为按需加载（Load As Needed）的深度素材，分别覆盖 CLI 命令、部署场景模式与 netlify.toml 配置。技能还携带 LICENSE.txt（Apache 2.0 协议），授权信息随技能目录一并分发。

该技能的核心自动化目标可概括为四件事：

1. 校验 Netlify CLI 认证状态；
2. 检测项目配置与框架类型；
3. 链接已存在的站点，或创建新站点；
4. 部署到生产（production）或预览（preview/draft）环境。

前置条件

在执行任何部署命令前，需满足以下环境要求：

• Netlify CLI：通过npx调用（npx netlify），无需全局安装；
• 认证：拥有处于活跃登录状态的 Netlify 账号；
• 项目：当前目录下存在一个有效的 Web 项目；
• 网络与超时：如果沙箱环境拦截了部署所需的网络请求，需要以sandbox_permissions=require_escalated重新运行；部署过程可能耗时数分钟，应使用合适的命令超时值。

认证模式：优先 OAuth，备选 API Token

技能采用"预认证的 Netlify CLI"（pre-authenticated Netlify CLI）模式，认证流程如下：

1. 用npx netlify status检查认证状态；
2. 若未认证，引导用户执行npx netlify login完成登录；
3. 若认证始终无法建立，则优雅失败（fail gracefully），不强行继续部署。

认证方式有两种：

API Token 方式只需导出环境变量即可：

export NETLIFY_AUTH_TOKEN=your_token_here

令牌在 Netlify 账号的 Personal Access Tokens 页面生成。配套的 CLI 命令参考 还补充了npx netlify logout（退出登录）与npx netlify status --verbose（查看详细状态）等认证相关命令。

标准工作流：六步完成部署

1. 校验 Netlify CLI 认证

npx netlify status

预期输出模式：

• ✅ 已认证：显示登录用户邮箱及站点链接状态；
• ❌ 未认证：提示 "Not logged into any site" 或认证错误。

若未认证，引导用户执行：

npx netlify login

命令会打开浏览器窗口完成 OAuth 认证。等待用户完成登录后，再次用npx netlify status复核。

2. 检测站点链接状态

从netlify status的输出中判断：

• 已链接（Linked）：站点已连接到 Netlify，输出中会显示站点名称/URL；
• 未链接（Not linked）：需要执行链接或创建操作。

3. 链接已有站点或创建新站点

• 已链接→ 直接跳到第 4 步；
• 未链接→ 优先尝试按 Git remote 链接：

# 确认项目是否基于 Git git remote show origin # 提取 remote URL # 格式示例: https://github.com/username/repo 或 git@github.com:username/repo.git # 按 Git remote 尝试链接 npx netlify link --git-remote-url <REMOTE_URL>

• 链接失败（站点在 Netlify 上不存在）→ 交互式创建新站点：

npx netlify init

netlify init会引导用户完成：① 选择团队/账号；② 设置站点名称；③ 配置构建设置；④ 按需生成netlify.toml。

4. 校验依赖

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

# npm 项目 npm install # 其他包管理器：检测后使用对应命令 # yarn install、pnpm install 等

5. 部署到 Netlify

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

预览/草稿部署（Preview/Draft，已有站点时的默认选择）：

npx netlify deploy

这会生成一个带唯一 URL 的部署预览，用于测试。

生产部署（Production，新站点或明确的线上发布）：

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查看站点或控制台。

完整示例工作流

# 1. 检查认证 npx netlify status # 若未认证: npx netlify login # 2. 链接站点（如需） # 优先尝试 Git-based 链接 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

处理 netlify.toml 与框架检测

如果项目根目录存在netlify.toml，CLI 会自动使用它；若不存在，CLI 会提示询问：

• 构建命令（Build command）：例如npm run build、next build；
• 发布目录（Publish directory）：例如dist、build、.next。

常见框架默认值：

技能会尽可能从package.json检测框架类型，并给出合适的设置建议。更完整的框架配置（Vue、Astro、SvelteKit 等）可参考 netlify.toml 配置参考，其中给出了 Vue/Astro 输出dist、SvelteKit 输出build等具体映射。

错误处理

部署模式参考 还给出了更细的错误恢复模式：

• "Publish directory not found"：原因通常是构建命令未生成预期输出目录。修复路径：本地运行npm run build→ 核对输出目录名 → 修正 netlify.toml 或 CLI 提示中的路径；
• "Command failed with exit code 1"：构建命令本身失败。修复路径：查看构建日志 → 本地复现npm run build→ 修复构建错误 → 重新部署；
• "Not logged in"：认证 token 过期或缺失。修复：npx netlify logout后重新npx netlify login。

故障排查：沙箱网络升级

如果部署因网络问题失败（超时、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访问。

CLI 命令参考 补充了命令行侧的环境变量操作：

# 列出环境变量 npx netlify env:list # 设置环境变量 npx netlify env:set KEY value # 获取环境变量值 npx netlify env:get KEY # 从 .env 文件导入 npx netlify env:import .env

实用技巧

• 先执行netlify deploy（不带--prod）做测试，再上生产；
• 运行netlify open在 Netlify 控制台查看站点；
• 运行netlify logs查看函数日志（使用 Netlify Functions 时）；
• 使用netlify dev进行带 Netlify 能力的本地开发。

部署决策树与典型场景

部署模式参考 将上述工作流浓缩为一棵决策树，适合作为 Agent 的执行导航：

Is user authenticated? ├─ No → Run `netlify login` └─ Yes → Is site linked? ├─ No → Is it a Git repo? │ ├─ Yes → Try `netlify link --git-remote-url` │ │ ├─ Success → Continue to deploy │ │ └─ Fail → Run `netlify init` │ └─ No → Run `netlify init` └─ Yes → Is this first deploy or existing site? ├─ First deploy/new site → `netlify deploy --prod` └─ Existing site → `netlify deploy` (preview)

场景一：全新项目首次部署

npx netlify status # Not linked to a site npx netlify login # Opens browser for authentication npx netlify init # Walks through site creation npm install npx netlify deploy --prod

场景二：将已有 Git 仓库链接到已存在的站点

git remote show origin # * remote origin # Fetch URL: https://github.com/user/my-app.git npx netlify link --git-remote-url https://github.com/user/my-app.git # Site linked successfully

场景三：预览部署（上线前测试）

# 修改代码后 npx netlify deploy # Draft deploy URL: https://507f1f77bcf86cd799439011-my-app.netlify.app # 测试通过后发布生产 npx netlify deploy --prod

场景四：框架特定部署

• Next.js：默认输出.next，netlify.toml 应包含command = "npm run build"、publish = ".next"；
• React (Vite)：默认输出dist，可先本地npm run build再用npx netlify deploy --dir=dist --prod；
• 静态 HTML：无需构建步骤，npx netlify deploy --dir=. --prod直接发布当前目录。

场景五：Monorepo 子目录部署

两种方式：进入子目录执行，或在 netlify.toml 中设置base：

[build] base = "packages/frontend" command = "npm run build" publish = "dist"

场景六：环境变量注入

npx netlify env:set API_KEY "secret_value" npx netlify env:set NODE_ENV "production"

代码中通过process.env.API_KEY读取，随后正常部署即可。

场景七：自定义域名

先完成生产部署，再通过npx netlify open:admin进入域名设置添加域名，按 Netlify 指引更新 DNS 记录，等待 DNS 传播（最长约 48 小时）。

netlify.toml 配置深度参考

netlify.toml 配置参考 提供了完整的文件级构建配置说明，下面按主题归纳。

基础结构与构建设置

[build] # 构建站点所用的命令 command = "npm run build" # 发布目录（相对仓库根目录） publish = "dist" # 函数目录 functions = "netlify/functions" # 基目录（非仓库根目录时使用，如 monorepo） base = "packages/frontend" # 满足条件时跳过构建 ignore = "git diff --quiet HEAD^ HEAD package.json"

环境变量

[build.environment] NODE_VERSION = "18" NPM_FLAGS = "--prefix=/dev/null" [context.production.environment] NODE_ENV = "production"

上下文（Context）差异化配置

不同部署上下文可使用不同构建命令与环境变量：

# 生产 [context.production] command = "npm run build:prod" [context.production.environment] NODE_ENV = "production" # 部署预览 [context.deploy-preview] command = "npm run build:preview" # 分支部署 [context.branch-deploy] command = "npm run build:staging" # 指定分支 [context.staging] command = "npm run build:staging"

重定向与重写

[[redirects]] from = "/old-path" to = "/new-path" status = 301 [[redirects]] from = "/api/*" to = "https://api.example.com/:splat" status = 200 # SPA 回退（客户端路由） [[redirects]] from = "/*" to = "/index.html" status = 200

还支持基于国家/地区的条件路由：

[[redirects]] from = "/" to = "/uk" status = 302 conditions = {Country = ["GB"]}

响应头

[[headers]] for = "/*" [headers.values] X-Frame-Options = "DENY" X-XSS-Protection = "1; mode=block" Content-Security-Policy = "default-src 'self'" [[headers]] for = "/assets/*" [headers.values] Cache-Control = "public, max-age=31536000, immutable"

函数（Serverless）配置

[functions] directory = "netlify/functions" node_bundler = "esbuild" [[functions]] path = "/api/*" function = "api"

构建插件与边缘函数

[[plugins]] package = "@netlify/plugin-lighthouse" [plugins.inputs] output_path = "reports/lighthouse.html" [[edge_functions]] function = "geolocation" path = "/api/location"

资源处理（Processing）

[build.processing] skip_processing = false [build.processing.css] bundle = true minify = true [build.processing.js] bundle = true minify = true [build.processing.html] pretty_urls = true [build.processing.images] compress = true

常用组合模式

SPA 应用（构建 + 全量回退到 index.html）：

[build] command = "npm run build" publish = "dist" [[redirects]] from = "/*" to = "/index.html" status = 200

Monorepo 基目录：

[build] base = "packages/web" command = "npm run build" publish = "dist"

配置校验

npx netlify build --dry

netlify build --dry以演练模式展示构建设置而不真正构建，用于校验 netlify.toml 的合法性。

CLI 命令速查

CLI 命令参考 汇总了部署相关的常用命令，按功能域划分：

认证

npx netlify login # 浏览器 OAuth 登录 npx netlify status # 检查认证状态与站点链接 npx netlify logout # 退出登录

站点管理

npx netlify link # 将当前目录链接到已有站点 npx netlify link --git-remote-url <url> # 按 Git remote URL 链接 npx netlify init # 创建并链接新站点 npx netlify unlink # 取消当前站点链接 npx netlify open # 在控制台打开站点 npx netlify open:admin # 打开站点管理后台 npx netlify open:site # 在浏览器打开站点

部署

npx netlify deploy # 预览/草稿部署（安全测试） npx netlify deploy --prod # 生产部署 npx netlify deploy --dir=dist # 指定目录部署 npx netlify deploy --message="Deploy message" # 带部署说明 npx netlify deploy:list # 列出所有部署

本地开发

npx netlify dev # 带 Netlify 能力的本地开发服务器 npx netlify dev --port 3000 # 指定端口

构建与站点信息

npx netlify build --dry # 展示构建设置（演练） npx netlify build # 本地执行构建 npx netlify sites:list # 列出站点 npx netlify api getSite --data '{"site_id": "YOUR_SITE_ID"}' # 查询站点信息

函数与日志

npx netlify functions:list # 列出函数 npx netlify functions:invoke FUNCTION_NAME # 本地调用函数 npx netlify functions:create FUNCTION_NAME # 新建函数 npx netlify logs # 流式查看函数日志 npx netlify logs:function FUNCTION_NAME # 查看指定函数日志

排障命令与退出码

npx netlify --version # 查看 CLI 版本 npx netlify help [command] # 查看任意命令帮助 npx netlify status --verbose

Netlify CLI 的退出码约定：

通用 Flags：--json（JSON 输出）、--silent（静默）、--debug（调试信息）、--force（跳过确认提示）。

最佳实践与性能建议

部署模式参考 总结的部署最佳实践：

1. 总是先预览再上生产：netlify deploy测试 → 充分验证 →netlify deploy --prod；
2. 用 netlify.toml 保证一致性：把构建命令、发布目录、重定向固化进仓库，确保每次部署行为一致；
3. 优先让 Netlify 自动检测框架：仅在框架无法被识别、需要自定义构建命令或项目结构非常规时才显式指定构建设置；
4. 部署前务必安装依赖：npm install（或 yarn/pnpm）后再部署；
5. 先本地构建验证：npm run build确认产物存在后再netlify deploy --dir=dist；
6. 使用部署说明：npx netlify deploy --prod --message="Fix login bug"，为每次部署留下上下文。

性能优化建议：

• 在 netlify.toml 中开启 processing 自动优化（如 CSS/JS 的bundle与minify）；
• 为静态资源配置长缓存头（Cache-Control: public, max-age=31536000, immutable）；
• 部署前优化图片，或使用 Netlify Image CDN；
• 用 Netlify Functions 承载服务端逻辑，减少对外部 API 的依赖。

小结

netlify-deploy 技能将"认证 → 检测 → 链接 → 构建 → 部署 → 汇报"这条完整链路封装成一套可被 Agent 直接遵循的操作手册，其核心价值在于：优先复用已认证的 CLI 会话、按 Git remote 智能链接既有站点、区分预览与生产部署以降低误发布风险，并通过 SKILL.md 与 references 三份参考文档的分层组织，让部署指令既可以快速执行，也能够在遇到框架差异、Monorepo、环境变量、自定义域名等复杂场景时按需深挖。对开发者而言，这套技能文档同时是一份相当完整的 Netlify CLI 实战手册，可直接迁移到日常部署工作中使用。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills