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

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 CLInpx 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.txtApache 2.0 协议授权信息随技能目录一并分发。该技能的核心自动化目标可概括为四件事校验 Netlify CLI 认证状态检测项目配置与框架类型链接已存在的站点或创建新站点部署到生产production或预览preview/draft环境。前置条件在执行任何部署命令前需满足以下环境要求Netlify CLI通过npx调用npx netlify无需全局安装认证拥有处于活跃登录状态的 Netlify 账号项目当前目录下存在一个有效的 Web 项目网络与超时如果沙箱环境拦截了部署所需的网络请求需要以sandbox_permissionsrequire_escalated重新运行部署过程可能耗时数分钟应使用合适的命令超时值。认证模式优先 OAuth备选 API Token技能采用预认证的 Netlify CLIpre-authenticated Netlify CLI模式认证流程如下用npx netlify status检查认证状态若未认证引导用户执行npx netlify login完成登录若认证始终无法建立则优雅失败fail gracefully不强行继续部署。认证方式有两种方式说明使用场景浏览器 OAuth首选netlify login打开浏览器完成授权常规开发环境API Token备选设置环境变量NETLIFY_AUTH_TOKEN无法使用浏览器交互的自动化环境API Token 方式只需导出环境变量即可export NETLIFY_AUTH_TOKENyour_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 或 gitgithub.com:username/repo.git # 按 Git remote 尝试链接 npx netlify link --git-remote-url REMOTE_URL链接失败站点在 Netlify 上不存在→ 交互式创建新站点npx netlify initnetlify 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。部署过程CLI 检测构建设置读取netlify.toml或向用户询问在本地构建项目上传构建产物到 Netlify返回部署 URL。6. 汇报结果部署完成后向用户汇报Deploy URL本次部署的唯一 URLSite URL生产 URL若为生产部署Deploy logsNetlify 控制台的日志链接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.tomlCLI 会自动使用它若不存在CLI 会提示询问构建命令Build command例如npm run build、next build发布目录Publish directory例如dist、build、.next。常见框架默认值框架构建命令发布目录Next.jsnpm run build.nextReact (Vite)npm run builddist静态 HTML无构建命令当前目录技能会尽可能从package.json检测框架类型并给出合适的设置建议。更完整的框架配置Vue、Astro、SvelteKit 等可参考 netlify.toml 配置参考其中给出了 Vue/Astro 输出dist、SvelteKit 输出build等具体映射。错误处理报错信息解决方案Not logged in运行npx netlify loginNo site linked运行npx netlify link或npx netlify initBuild failed检查 netlify.toml 或 CLI 提示中的构建命令与发布目录确认依赖已安装查看构建日志定位具体错误Publish directory not found确认构建命令成功执行检查发布目录路径是否正确部署模式参考 还给出了更细的错误恢复模式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_permissionsrequire_escalated——当沙箱网络拦截出站请求时部署必须获得升级后的网络访问权限。此时可向用户给出如下引导The deploy needs escalated network access to deploy to Netlify. I can rerun the command with escalated permissions—want me to proceed?环境变量管理对于密钥与配置绝不把密钥提交进 Git在 Netlify 控制台设置Site Settings → Environment Variables在构建中通过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默认输出.nextnetlify.toml 应包含command npm run build、publish .nextReact (Vite)默认输出dist可先本地npm run build再用npx netlify deploy --dirdist --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; modeblock Content-Security-Policy default-src self [[headers]] for /assets/* [headers.values] Cache-Control public, max-age31536000, 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 200Monorepo 基目录[build] base packages/web command npm run build publish dist配置校验npx netlify build --drynetlify 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 --dirdist # 指定目录部署 npx netlify deploy --messageDeploy 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 --verboseNetlify CLI 的退出码约定退出码含义0成功1一般错误2认证错误3站点未找到4构建失败通用 Flags--jsonJSON 输出、--silent静默、--debug调试信息、--force跳过确认提示。最佳实践与性能建议部署模式参考 总结的部署最佳实践总是先预览再上生产netlify deploy测试 → 充分验证 →netlify deploy --prod用 netlify.toml 保证一致性把构建命令、发布目录、重定向固化进仓库确保每次部署行为一致优先让 Netlify 自动检测框架仅在框架无法被识别、需要自定义构建命令或项目结构非常规时才显式指定构建设置部署前务必安装依赖npm install或 yarn/pnpm后再部署先本地构建验证npm run build确认产物存在后再netlify deploy --dirdist使用部署说明npx netlify deploy --prod --messageFix login bug为每次部署留下上下文。性能优化建议在 netlify.toml 中开启 processing 自动优化如 CSS/JS 的bundle与minify为静态资源配置长缓存头Cache-Control: public, max-age31536000, 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考