netlify-cli-and-deploy

Netlify CLI 和部署

安装

npm install -g netlify-cli    # Global (for local dev)
npm install netlify-cli -D    # Local (for CI)

需要 Node.js 18.14.0 或更高版本。

身份验证

netlify login       # Opens browser for OAuth
netlify status      # Check auth + linked site status

在 CI 中，请改为设置 NETLIFY_AUTH_TOKEN 环境变量。

CI 还需要一个目标站点。 NETLIFY_AUTH_TOKEN 只负责验证你的身份，不会选择部署要发布到哪个站点。在 CI 中，没有已关联的 .netlify/state.json，因此还需要将 NETLIFY_SITE_ID（站点的 API/Project ID，在站点配置中显示为 Project ID）设为环境变量，以便 netlify deploy 知道要发布到哪里。若未设置，CI 部署就没有目标站点，会失败或尝试提示你操作。本地通过 netlify link 处理，它会将站点 ID 写入 .netlify/state.json；CI 中没有此文件。

关联站点

使用 netlify status 检查是否已关联。若没有：

# Interactive
netlify link

# By Git remote (if using Git)
netlify link --git-remote-url https://github.com/org/repo

# Create new site
netlify init           # With Git CI/CD setup
netlify init --manual  # Without Git CI/CD

站点 ID 存储在 .netlify/state.json 中。将 .netlify 添加到 .gitignore。

部署

基于 Git 的部署（持续部署）

使用 netlify init 进行设置。推送或 PR 会触发自动部署：

• 推送到生产分支 → 生产部署
• 创建 PR → 使用唯一 URL 的部署预览
• 推送到其他分支 → 仅当启用了分支部署时才会进行分支部署。默认情况下，分支部署处于关闭状态；请在站点的构建和部署设置中启用（可针对每个分支单独启用，也可为所有分支启用）

构建在 Netlify 的服务器上运行。在 netlify.toml 中配置构建设置。

netlify.toml 会覆盖 UI 设置。 netlify.toml 中的基于文件的配置优先于 Netlify UI 中配置的对应构建设置。同一选项在两处都有设置时，以提交到仓库的 netlify.toml 为准；除非修改文件并重新部署，否则在控制面板中编辑该设置不会生效。有人会在 UI 中调整构建命令、发布目录或基础目录，却发现每次部署仍沿用已提交的旧值，对此感到意外。

单体仓库中的配置查找顺序。 在单体仓库中，Netlify 会按以下顺序查找 netlify.toml，并使用找到的第一个文件：（1）软件包目录；（2）基础目录；（3）仓库根目录。请将站点专属的 netlify.toml 放在软件包目录（即包含该站点的子目录）中，使其优先于根目录级别的配置。根目录级别的 netlify.toml 中设置的基础目录也会覆盖 UI 中配置的基础目录。

手动／本地部署（无需 Git）

在本地构建，然后上传：

netlify deploy          # Draft deploy (preview URL)
netlify deploy --prod   # Production deploy
netlify deploy --dir=dist  # Specify output directory

无需 Git 即可使用此方式，适用于原型、仅在本地运行的项目或 CI 流水线。

手动执行的 --prod 部署会被下一次 Git 推送替换。 如果同一站点也已连接 Git 持续部署，那么下一次推送到生产分支时会触发新的构建，并自动发布，替换你手动发布的 --prod 部署；手动发布的构建会悄然从生产环境中消失。若要让特定部署持续生效，请在 UI 的站点 Deploys 列表中锁定已发布的部署（“Stop auto publishing”）：锁定期间，新推送仍会触发构建，但不会自动发布，直到你解除锁定或手动发布。否则，在同一生产分支上混用手动 --prod 部署和 Git CD，最终以最近提交为准。

部署 URL 可通过链接公开访问

草稿部署（netlify deploy）、部署预览、分支部署和部署永久链接各自都有一个任何持有链接的人都可以打开的唯一 URL；URL 难以猜测且未公开列出，并不意味着它们是私有的。不要仅凭这一点就把预览 URL 当作存放机密或未发布内容的安全位置。若要实际限制访问，请在 UI 中启用站点保护（密码保护或团队／SSO 保护）；你可以保护所有部署，也可以只保护非生产部署。

本地开发

选项 1：netlify dev

netlify dev

它会封装你的框架开发服务器，并提供：

• 注入环境变量
• Functions 和边缘 Functions
• 处理重定向和标头

选项 2：Netlify Vite 插件（基于 Vite 的项目）

对于使用 Vite 的项目（React SPA、TanStack Start、SvelteKit、Remix），Vite 插件可直接在框架的开发服务器中提供 Netlify 平台原语：

npm install @netlify/vite-plugin

// vite.config.ts
import netlify from "@netlify/vite-plugin";
export default defineConfig({ plugins: [netlify()] });

然后运行常规开发命令（npm run dev）——无需使用 netlify dev 包装器。这样你就可以在开发期间使用 Blobs、DB、Functions 和环境变量。

请参阅 netlify-frameworks 技能，了解针对特定框架的本地开发指南。

环境变量

CLI 管理

# Set
netlify env:set API_KEY "value"
netlify env:set API_KEY "value" --secret              # Hidden from logs
netlify env:set API_KEY "value" --context production   # Context-specific

# Get
netlify env:get API_KEY

# List
netlify env:list
netlify env:list --plain > .env                        # Export to file

# Import from file
netlify env:import .env

# Delete
netlify env:unset API_KEY

按上下文限定范围

变量可以限定到不同的部署上下文：

netlify env:set API_URL "https://api.prod.com" --context production
netlify env:set API_URL "https://api.staging.com" --context deploy-preview
netlify env:set DEBUG "true" --context branch:feature-x

在代码中访问

• 服务端（Functions）：使用 Netlify.env.get("VAR")（首选）或 process.env.VAR
• 客户端（Vite）：只能通过 import.meta.env.VITE_VAR 访问带 VITE_ 前缀的变量
• 客户端（Astro）：只能通过 import.meta.env.PUBLIC_VAR 访问带 PUBLIC_ 前缀的变量

切勿为机密信息使用 VITE_ 或 PUBLIC_ 前缀——这些变量会暴露给浏览器。

命令失败时，报告问题并停止

当 netlify 命令、部署或 netlify dev 失败时，请向用户报告失败情况，并提供确切错误、部署日志 URL（CLI 会打印该 URL）以及受影响的网站／分支，然后停止。不要编造恢复命令，也不要升级到更底层的工具：不要 curl https://api.netlify.com/...，不要运行 netlify api <method> 作为恢复手段，也不要从磁盘读取身份验证令牌来强行完成操作。如果文档所述的正常流程无法运行，这是平台状态问题，用户需要知晓。

常用命令

命令	说明
netlify status	身份验证和网站关联状态
netlify dev	启动本地开发服务器
netlify build	在本地运行构建（模拟 Netlify 环境）
netlify deploy	草稿部署
netlify deploy --prod	生产环境部署
netlify dev:exec <cmd>	在加载 Netlify 环境的情况下运行命令
netlify env:list	列出环境变量
netlify clone org/repo	一步完成克隆、关联和设置