Netlify CLI 部署命令全指南netlify-deploy Skill 的命令速查与实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文是 Codex 生态中netlify-deploySkill位于 skills/.curated/netlify-deploy/SKILL.md配套 CLI 命令参考文档的完整实战解读覆盖认证、站点管理、部署、本地开发、环境变量、Serverless Functions、日志与故障排查等全部命令面。读完本文你将掌握通过npx netlify完成从登录鉴权到生产发布的全链路部署操作并能依据退出码与通用 Flags 快速定位和解决部署问题。一、这份命令参考在 Skill 中的定位在netlify-deploySkill 中cli-commands.md 属于按需加载的捆绑参考资料Bundled References与 netlify.toml 配置参考、部署模式文档 并列。Skill 的主流程见 SKILL.md负责检测认证 → 判断站点关联 → 链接或新建站点 → 安装依赖 → 选择部署类型 → 汇报结果而命令参考则提供了每个环节对应的具体命令与参数。Skill 的 Agent 接口定义agents/openai.yaml表明该 Skill 的典型调用方式是npx netlify系列命令——即无需全局安装 CLI直接通过npx拉取并执行。本文所有命令均以npx netlify为前缀可直接复制运行。二、认证命令AuthenticationNetlify CLI 的所有操作都以登录态为前提。认证相关命令如下# 通过浏览器 OAuth 登录 npx netlify login # 检查认证状态与站点关联情况 npx netlify status # 退出登录 npx netlify logout从 SKILL.md 的认证模式看Skill 采用预认证的 Netlify CLI策略具体分为两类浏览器 OAuth首选npx netlify login会打开浏览器完成授权。npx netlify status的预期输出有两种已登录时显示登录用户邮箱与站点链接状态未登录时提示 Not logged into any site 或认证错误。API Key备选设置环境变量NETLIFY_AUTH_TOKEN即可免浏览器认证适合无浏览器环境或 CI 场景export NETLIFY_AUTH_TOKENyour_token_here退出登录后再次认证的恢复模式为npx netlify logout npx netlify login见 deployment-patterns.md 的 Error Recovery Patterns。三、站点管理命令Site Management站点关联是部署的前置步骤。核心命令如下# 将当前目录关联到已有站点交互式选择 npx netlify link # 通过 Git 远端 URL 关联站点适合自动化 npx netlify link --git-remote-url url # 创建并关联新站点交互式引导 npx netlify init # 解除与当前站点的关联 npx netlify unlink # 在 Netlify Dashboard 中打开站点 npx netlify open # 打开站点管理后台 npx netlify open:admin # 在浏览器中打开站点 npx netlify open:site结合 deployment-patterns.md 中的部署决策树链接逻辑是先检查是否 Git 仓库git remote show origin若是则优先尝试npx netlify link --git-remote-url REMOTE_URL链接失败说明 Netlify 上尚无此站点则执行npx netlify init。init会引导完成选择团队/账号、设置站点名、配置构建设置并在需要时生成netlify.toml。四、部署命令Deployment部署是 Skill 的核心环节命令速查# 部署为预览/草稿安全测试用生成唯一预览 URL npx netlify deploy # 部署到生产环境发布到正式 URL npx netlify deploy --prod # 指定发布目录部署 npx netlify deploy --dirdist # 携带部署说明信息 npx netlify deploy --messageDeploy message # 列出所有历史部署 npx netlify deploy:list两条部署路径的适用场景依据 SKILL.md 与 deployment-patterns.mdPreview/Draft Deploy对已有站点默认执行npx netlify deploy产出形如https://hash-my-app.netlify.app的草稿 URL 供测试是先预览后发布最佳实践的第一步。Production Deploy对新站点或明确需要生产发布时执行npx netlify deploy --prod直接发布到线上正式 URL。部署内部流程为CLI 读取构建设置来自netlify.toml或交互提示→ 本地执行构建 → 上传构建产物到 Netlify → 返回部署 URL。--dir参数适用于本地已构建完成、仅上传产物的场景如 Vite 项目执行npm run build后npx netlify deploy --dirdist --prod--message可为部署添加上下文便于追溯例如npx netlify deploy --prod --messageFix login bug。五、本地开发命令Development# 启动本地开发服务器包含 Netlify Functions 等平台能力 npx netlify dev # 指定端口启动 npx netlify dev --port 3000netlify dev的价值在于本地复刻 Netlify 运行环境可以联调 Serverless Functions、模拟重定向与 Headers 等平台特性避免本地正常、线上异常的割裂。配合functions:invoke可对函数做本地调试见下文。六、站点信息查询命令Site Information# 列出账号下的所有站点 npx netlify sites:list # 通过 API 获取指定站点详情需替换站点 ID npx netlify api getSite --data {site_id: YOUR_SITE_ID}api子命令直接透传 Netlify API适合在脚本中获取结构化站点数据加上通用 Flags 中的--json可得到机器可读输出便于 Agent 解析。七、环境变量管理命令Environment Variables# 列出环境变量 npx netlify env:list # 设置环境变量KEY 与 value 以空格分隔 npx netlify env:set KEY value # 获取某个环境变量的值 npx netlify env:get KEY # 从 .env 文件批量导入 npx netlify env:import .env配合 netlify.toml 配置参考 中的[build.environment]与[context.*.environment]段落可以在文件配置与 CLI 管理之间灵活选择。实践要点来自 SKILL.md 与 deployment-patterns.md严禁将密钥提交到 Git生产环境建议在 Netlify DashboardSite Settings → Environment Variables或通过npx netlify env:set API_KEY secret_value设置构建/运行时通过process.env.API_KEY访问。八、构建命令Build# 仅展示构建配置不实际构建用于校验 netlify.toml 与检测设置 npx netlify build --dry # 本地完整执行一次构建 npx netlify buildnetlify build --dry是验证netlify.toml配置是否合法的推荐手段见 netlify-toml.md 的 Validation 小节它会打印将要执行的构建命令、发布目录、环境变量等信息属于低成本高价值的排错动作。建议在正式部署前先本地执行npm run build确认产物存在再使用npx netlify deploy --dir构建目录上传Best Practices 中的Build Locally First。九、Serverless Functions 命令FunctionsNetlify Functions 让静态站点具备服务端能力相关命令# 列出项目中的函数 npx netlify functions:list # 在本地调用指定函数联调调试 npx netlify functions:invoke FUNCTION_NAME # 交互式创建新函数脚手架模板 npx netlify functions:create FUNCTION_NAME函数目录可在netlify.toml中配置[functions] directory netlify/functions并可通过node_bundler esbuild指定打包器。部署后如需排查线上函数问题配合下一节的日志命令使用。十、日志命令Logs# 实时流式查看函数日志 npx netlify logs # 查看指定函数的日志 npx netlify logs:function FUNCTION_NAME日志是排查线上函数运行时错误的关键证据。netlify dev环境下的本地调试输出与logs的线上日志配合可以完成本地复现 → 线上确认的完整闭环。十一、故障排查命令Troubleshooting Commands# 查看 CLI 版本 npx netlify --version # 查看任意命令的帮助 npx netlify help [command] # 以详细输出检查状态 npx netlify status --verbose三个命令构成排错三板斧先确认 CLI 版本与运行环境再用help查看目标命令的完整参数最后用status --verbose输出详细的认证与站点信息。常见故障与修复依据 SKILL.md 的 Error Handling 与 deployment-patterns.md 的 Error Recovery PatternsNot logged in→ 执行npx netlify loginNo site linked→ 执行npx netlify link或npx netlify initBuild failed→ 检查netlify.toml中的构建命令与发布目录确认依赖已安装查看构建日志定位具体错误Publish directory not found→ 本地执行构建命令确认产物目录名并核对netlify.toml中publish路径Command failed with exit code 1→ 查看构建日志、本地复现构建错误、修复后重新部署十二、退出码Exit CodesCLI 以退出码向脚本与 Agent 传递结果状态退出码含义0成功1一般错误2认证错误3站点未找到4构建失败在自动化脚本如 CI 或 Agent 编排中应根据退出码分支处理2触发重新登录或刷新NETLIFY_AUTH_TOKEN3触发link/init4进入构建排错流程。十三、通用 FlagsCommon Flags以下 Flags 适用于大部分子命令用于控制输出与交互行为--json— 以 JSON 格式输出便于程序解析--silent— 抑制输出--debug— 输出调试信息--force— 跳过确认提示适合非交互式自动化对 Agent 场景--json是最常用的组合例如npx netlify deploy --json可返回结构化部署结果URL、日志等供后续步骤直接读取。十四、端到端部署工作流串联将以上命令按 SKILL.md 的完整工作流串联即是一个可落地的端到端示例# 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 # 6. 汇报结果打开站点/管理后台查看 npx netlify open:site npx netlify open:admin部署完成后建议汇报本次部署的 URL、生产 URL如为生产部署、部署日志入口以及后续可执行的netlify open操作。若需固化构建与发布配置可将[build] command / publish、[[redirects]]、[[headers]]、[functions]、[build.processing]等内容写入仓库根目录的netlify.toml详见 netlify.toml 配置参考从而保证不同环境下部署行为一致。完整的多场景决策树与最佳实践先预览后生产、依赖先装、本地先构建、部署消息留痕、静态资源缓存头等可进一步参考 部署模式文档。注意事项命令统一使用npx netlify形式无需全局安装如需固定版本可结合--version输出确认。若沙箱环境拦截部署所需的网络请求需要以升级权限重新执行部署命令对应sandbox_permissionsrequire_escalated完整部署过程可能耗时数分钟应设置合适的命令超时。退出码是脚本化部署的事实标准自动化集成时应优先以退出码而非文本输出判断成败。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考