PuppyIP 资源中心
开发环境教程 6 分钟 发布于 2026-11-18

Cloudflare Artifacts 本地开发:Git 版本、仓库隔离与事件限制

当前工具版本下,Artifacts 绑定默认使用本机模拟仓库,与已部署仓库和令牌分开。先检查启动开发进程的环境能否找到 Git 2.32 或更新版本,再明确选择本地或远程绑定;本地 Git push 成功,也不会触发依赖 push 事件的 Workflow。

Cloudflare Artifacts Wrangler 本地开发 Git

服务对象与地域限制

PuppyIP 仅面向海外合规企业及其授权人员提供服务,不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动,严禁在中国大陆境内使用本服务。

代理 IP 或服务器位于境外,不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。

本文要点

  • 本地模式需要 Git 2.32 或更新版本;Wrangler、Vite 插件与 Vitest 插件也有各自最低版本。
  • 当前版本省略 remote 或设为 false 都使用本地仓库;true 才连接已部署服务,并需要 Cloudflare 授权。
  • 旧 Vite 1.x 和已弃用的 vitest-pool-workers 保留较早的远程默认行为,不能套用新版本结论。
  • 本地只发布部分仓库生命周期和令牌事件;不发布 push、clone、fetch 事件,投递失败也不重试。

先检查 Git 和实际使用的开发工具版本

Cloudflare 于2026年11月16日公布 Artifacts 本地开发支持。Artifacts 是兼容 Git 的仓库存储服务;这里的本地模拟器让 Worker 在开发机上使用独立仓库,不会因为创建、推送或删除本地仓库就改动已部署仓库。

在真正启动开发服务器或测试的同一个终端、容器或远程开发环境中检查 Git。要求 Git 2.32 或更新版本,并且该进程的 PATH 能找到它;宿主机安装了 Git,不代表容器或编辑器启动的进程也能找到。修改 PATH 后重启开发工具。

工具门槛分别是 Wrangler 4.163.0 或更新版本、Cloudflare Vite 插件 2.0.0-rc.0 或更新版本,或者 @cloudflare/vitest-plugin 1.8.3 或更新版本。按项目实际使用的入口核对,不需要为了这篇教程同时换用三套工具。Git 缺失或版本过旧时,本地 Artifacts 会在启动阶段报错并提示安装或升级。

检查当前环境中的 Git

shell
git --version
在启动开发服务器或测试的同一环境运行;输出的版本应至少为2.32。

本地看不到线上仓库,先确认绑定模式

对于上述当前版本,省略 remote 或设置 remote = false 都选择本地模拟器,本地绑定本身不需要 Cloudflare 凭据。设为 remote = true 才访问已部署的 Artifacts 服务,需要开发工具获得 Cloudflare 授权;这会操作真实远程资源,不能用来解决“想保持本地隔离”的问题。

在现有 Wrangler TOML 配置中,可明确把对应绑定设为本地。下面只是配置片段,保留项目已有入口、兼容日期及其他设置;已有 ARTIFACTS 绑定时修改该条目,避免重复添加。namespace 使用相同名称,也不会把已部署命名空间中的仓库导入本地,两种模式之间不会自动同步。

省略 remote 时,wrangler dev、getPlatformProxy() 和 Vite 插件会提示默认使用本地模拟器。显式设置 false 可以保留本地行为并消除该提示;cloudflare.config.ts 对应设置使用 dev: { remote }。

Cloudflare Vite 插件1.x 有例外:启用远程绑定时,省略 remote 仍使用已部署仓库,要显式设为 false 才用本地。已弃用的 @cloudflare/vitest-pool-workers 也保留较早的远程默认行为,缺少 Cloudflare 凭据会失败;本地测试应迁移到当前 @cloudflare/vitest-plugin,再按其配置核对。

现有 Wrangler TOML 的本地绑定片段

text
[[artifacts]]
binding = "ARTIFACTS"
namespace = "default"
remote = false
按项目实际绑定名和命名空间调整;此片段不是完整 Worker 项目配置。

启动后使用返回的本地地址和仓库令牌

在已有 Worker 项目中,使用项目原有开发入口。使用 Wrangler 的项目可从项目根目录启动开发服务器;这条命令会启动本地服务,不是生产部署。Vite 或 Workers Vitest 项目使用各自已有入口和相应配置。

通过 env.ARTIFACTS.create() 创建仓库后,使用返回的 remote 地址和初始 token 进行标准 Git clone 或 push。本地地址使用回环 HTTP,仅指向开发机;这里的 token 是仓库凭据,不是 Cloudflare API token。不要把令牌写入源码、Git 配置或日志。

“本地绑定不需要 Cloudflare 凭据”只描述该绑定的模拟模式,不代表整个 Worker 的其他绑定、HTTPS 仓库导入或外部请求都能离线工作。线上服务的套餐、费用与地区资格需另按对应文档和账号条款核实;本地模式说明不能用来推断这些条件。

在已有 Wrangler 项目启动开发服务器

shell
npx wrangler dev
先确认当前目录、项目依赖和本地绑定;启动后以实际返回的仓库地址为准。

push 成功为什么没有启动本地 Workflow?

当前本地模拟器不发布 push、clone、fetch 事件,因此依赖 push 事件构建或部署的 Workflow 不会在本地启动。应先核对事件类型,不能把 Git 推送成功当作整个事件流程已经验证。

本地支持仓库创建、导入、fork、删除,以及仓库令牌创建和撤销事件。创建、导入或 fork 仓库时,初始令牌也会产生创建事件。事件目标须为同一个 Worker 定义的 Workflow;本地支持 Workflows,不支持投递到 Queues。Vite 插件1.x 还不能从本地事件启动 Workflow。

这些事件在仓库变更完成后投递,顺序没有保证;投递失败会写日志,不会重试,也不会让已经成功的仓库操作失败。检查仓库操作和 Workflow 实例时应分别确认结果。若在 cloudflare.config.ts 中声明事件,需要 cf 1.0.0-rc.0 或更新版本;直接导入 @cloudflare/config 时,对应包也至少为1.0.0-rc.0。

重启后仓库丢失,或 HTTPS 导入失败怎么办?

先核对项目根目录和持久化设置。启用持久化时,Wrangler 与 Vite 1.x 通常把状态放在 .wrangler/state/,Vite 2.x 使用 .cloudflare/state/;persistState: false 则使用临时状态。切换目录、配置或临时模式后,不应直接判断线上仓库被删除。

需要重置本地数据时,先停止开发服务器并保留需要的仓库,再仅处理所用状态路径下的 artifacts/ 子目录。不要为清理 Artifacts 一并删除其他绑定的状态,也不要把本地清理操作用于已部署服务。

HTTPS 导入由开发机上的 Git 执行,该环境必须能够连接源仓库。使用可信仓库的最终 HTTPS Git 地址,导入不跟随 HTTP 重定向。若内部 Git 服务使用私有 CA,可在启动开发进程前通过 GIT_SSL_CAINFO 指定可信 CA 文件;不要关闭 TLS 证书校验来掩盖证书链问题。

资料来源

常见问题

本地能用 Artifacts REST API、CLI、SSH 或 Git LFS 吗?

当前模拟器通过 wrangler dev、Cloudflare Vite 插件和 Workers Vitest 提供,不提供本地 REST API、Artifacts CLI、仪表盘、SSH 端点或 Git LFS 服务器。不要把已部署服务的接入方式直接套到本地。

重启后已有 clone 连不上,是否需要重建仓库?

先检查端口。开发服务器会把本地 Git 端口随状态保存并在重启后复用;如果端口已被其他进程占用,会选择新端口。从绑定获取新的实际 remote,再更新已有 clone 的 origin 地址,不必仅凭连接失败就重建仓库。

本地能推送任意大小的单个文件吗?

不能。当前本地模拟器会拒绝包含单个大于32 MiB文件的推送;读取超过该大小的文件会出现 MEMORY_LIMIT。这里是本地模拟器限制,不应推断为所有已部署套餐的存储或计费规则。