GitHub + Cloudflare 多账号 CLI 开发环境隔离指南

适用场景：同一台电脑同时维护多个项目，每个项目可能属于不同的 GitHub / Cloudflare 账号，希望 Codex、Claude Code 等开发 Agent 可以直接通过 CLI 开发、提交、部署，而不频繁手动切换账号。

---

1. 最终目标

希望本机形成：

项目 A/
├── GitHub → Account A
└── Cloudflare → Account A

项目 B/
├── GitHub → Account B
└── Cloudflare → Account B

日常开发只需要：

cd project-a

git pull
git push

npx wrangler dev
npx wrangler deploy

尽量不再处理网页登录、logout/login 或全局账号切换。

---

2. GitHub 和 Cloudflare 要分开理解

GitHub

有两个不同概念：

gh CLI 身份
≠
git push / pull 身份

gh auth login 管的是 GitHub CLI。

而：

git pull
git push

真正使用哪个账号，还与 Git remote、SSH Key / Credential Manager 有关。

---

Cloudflare

Wrangler 同样有两个概念：

认证凭据
+
目标 Account ID

必须两者匹配。

只写 account_id 并不能完成账号隔离。

account_id 只告诉 Wrangler：

我要操作哪个 Cloudflare Account。

它并没有告诉 Wrangler：

用哪个身份认证。

所以最稳定的项目级方案是：

CLOUDFLARE_API_TOKEN
+
CLOUDFLARE_ACCOUNT_ID

两个一起固定在项目环境中。

---

3. 新项目推荐流程

以后新合作项目直接按照下面做。

第一步：建立项目账号

如果项目需要完全独立：

项目邮箱
    ↓
GitHub Account
    ↓
Cloudflare Account

这三个身份保持一致，后续交接也简单。

---

4. GitHub CLI 配置

首先登录新账号：

gh auth login

查看本机已经保存的 GitHub 身份：

gh auth status

GitHub CLI 支持同一台机器保存多个 GitHub.com 账号。需要时可以：

gh auth switch --user <username>

切换当前活动账号。

一个非常重要的问题

gh auth switch 只影响当前 Terminal 吗？

不是。

它修改的是 GitHub CLI 保存的当前活动身份。

所以：

gh auth switch --user A

之后，其他新开的 Terminal 执行 gh 时也会看到 A 是活动账号。

因此它不适合作为真正的“项目目录级隔离”。

---

5. GitHub 项目隔离建议

对于日常 Agent 开发，最重要的是保证：

git pull
git push

不会推错账号。

推荐让每个项目使用自己对应的 Git remote / SSH 身份。

同时在项目目录执行：

git config user.name "项目GitHub用户名"
git config user.email "项目邮箱"

注意：

不要加 --global。

查看：

git config user.name
git config user.email
git remote -v

这样至少：

Commit 作者身份
+
Git Repository

都是项目级固定的。

如果需要严格保证多个 GitHub 账号完全互不干扰，可以进一步使用：

不同 SSH Key
+
~/.ssh/config Host Alias

这是比频繁 gh auth switch 更稳定的方式。

---

6. Cloudflare Wrangler 登录

普通登录：

npx wrangler login

正常逻辑是：

Wrangler
   ↓
启动 localhost:8976
   ↓
浏览器 Cloudflare OAuth
   ↓
浏览器回调 localhost:8976
   ↓
CLI 获得 Token

---

7. 本次真实踩坑：网页登录成功，但 CLI 一直没反应

实际遇到的情况：

npx wrangler login

浏览器：

Cloudflare 授权成功

但是 Terminal：

一直等待
没有完成认证

原因是默认 Wrangler OAuth 需要浏览器回调：

localhost:8976

如果本地网络、代理、浏览器、Git Bash 或其他环境导致这个 callback 无法完成，就会出现：

网页已经授权，但 CLI 收不到授权结果。

Cloudflare 在 Wrangler 4.119.0+ 已经提供 Device Authorization Flow，专门避免 localhost callback。

---

8. 解决方式：Device Login

直接使用：

npx wrangler login --device

这是本次实际验证可行的方法。

它不会启动：

localhost:8976

而是：

CLI 给出验证码
    ↓
浏览器登录
    ↓
输入/确认验证码
    ↓
CLI 主动轮询 Cloudflare
    ↓
认证成功

因此以后如果：

npx wrangler login

出现浏览器认证完成但 CLI 卡死，

不要继续折腾代理。

直接：

Ctrl + C

然后：

npx wrangler login --device

即可。

---

9. 一个错误命令

本次还踩过：

npx wrangler auth login

会得到：

Unknown argument: login

不要使用。

普通 OAuth 登录是：

npx wrangler login

Device Flow：

npx wrangler login --device

---

10. Wrangler Auth Profile

新版 Wrangler 提供：

npx wrangler auth create <profile>
npx wrangler auth activate <profile>
npx wrangler auth list

它本来非常适合这种场景：

project-a/
→ profile A

project-b/
→ profile B

进入对应目录以后自动选择对应 Cloudflare 身份。Cloudflare 官方就是把 Auth Profile 定位为多账号 / 客户项目隔离方案。

但是本次实际环境遇到了另外一个问题：

npx wrangler auth create <your-profile-name>

仍然使用：

localhost:8976

进行 OAuth callback。

结果再次出现：

浏览器授权成功
CLI 无响应

官方当前 auth create 提供 --callback-host、--callback-port，但没有与 wrangler login --device 对应的 --device 参数。

因此：

在当前机器环境下，不把 Auth Profile 作为主要方案。

---

11. Cloudflare 最稳定的项目级隔离方案

直接使用：

项目级 API Token
+
项目级 Account ID

每个项目拥有自己的：

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID

Wrangler 官方支持这两个系统环境变量，并且推荐通过项目目录 .env 保存本地环境配置。

项目：

project/
├── src/
├── wrangler.jsonc
├── .env
└── .gitignore

.env：

CLOUDFLARE_ACCOUNT_ID=<PROJECT_ACCOUNT_ID>
CLOUDFLARE_API_TOKEN=<PROJECT_API_TOKEN>

.gitignore：

.env
.env.*
.dev.vars
.dev.vars.*

API Token 绝对不要提交 GitHub。

Cloudflare 官方同样明确要求 .env / .dev.vars 中的 secret 不应提交 Git。

---

12. Wrangler 配置再固定 Account ID

推荐同时在：

wrangler.jsonc

中明确指定：

{
  "name": "my-worker",
  "account_id": "<PROJECT_ACCOUNT_ID>"
}

这样形成双保险：

.env
├── CLOUDFLARE_API_TOKEN   → 我是谁
└── CLOUDFLARE_ACCOUNT_ID  → 我要操作谁

wrangler.jsonc
└── account_id             → 再次固定目标账号

Cloudflare 官方支持 account_id 放在 Wrangler 配置文件中。

---

13. 为什么 API Token 方案最适合 Agent 开发

这样 Codex / Claude Code 不需要理解：

现在 Wrangler 登录的是哪个账号？
是不是需要 logout？
是不是需要重新 OAuth？

Agent 只要进入：

cd project

然后：

npx wrangler dev
npx wrangler deploy

Wrangler 会读取当前项目自己的：

.env

从而使用这个项目对应的：

Cloudflare API Token
Cloudflare Account ID

不同项目之间完全可以是不同账号。

---

14. 旧项目怎么办？

旧项目也按完全相同的方式做一次：

旧项目/
├── 旧账号 API Token
├── 旧账号 Account ID
└── wrangler.jsonc

新项目：

新项目/
├── 新账号 API Token
├── 新账号 Account ID
└── wrangler.jsonc

之后：

cd old-project
→ old Cloudflare

cd new-project
→ new Cloudflare

不用反复：

wrangler logout
wrangler login

---

15. 一个重要纠正：只固定 Account ID 不够

之前很容易产生这样的理解：

wrangler.jsonc
account_id = A

于是认为：

以后进入项目自动就是 Cloudflare A。

不完全正确。

正确模型是：

Authentication
+
Account Target

即：

API Token A
+
Account ID A

才能形成真正完整的项目级隔离。

如果：

当前 OAuth 登录的是账号 B

但：

wrangler.jsonc → Account A

Wrangler 并不会因此自动获得账号 A 的权限。

结果通常是：

权限错误 / 无法部署

而不是自动切换账号。

所以真正推荐的是：

CLOUDFLARE_API_TOKEN=A
CLOUDFLARE_ACCOUNT_ID=A

一起固定。

---

16. OAuth Login 以后还有没有用？

有。

例如第一次测试 Cloudflare CLI 时：

npx wrangler login --device
npx wrangler whoami

很方便。

但是长期维护多个项目时：

OAuth Login

更适合：

人临时使用 CLI。

而：

API Token + Account ID

更适合：

项目、Agent、自动化、CI/CD。

Cloudflare 官方也明确支持 API Token 用于 Wrangler 自动化和 CI/CD。

---

17. 查看当前 Cloudflare 身份

执行：

npx wrangler whoami

用于确认 Wrangler 当前真正使用的身份和可访问账号。

在任何重要 deploy 前，如果不确定，直接：

npx wrangler whoami

然后：

npx wrangler deploy

---

18. 以后新项目完整 SOP

Step 1：创建项目身份

项目邮箱
GitHub Account
Cloudflare Account

---

Step 2：GitHub

gh auth login
gh auth status

项目目录：

git config user.name "<USERNAME>"
git config user.email "<EMAIL>"
git remote -v

确保 remote 指向正确项目。

---

Step 3：Cloudflare

临时 OAuth 测试：

npx wrangler login --device
npx wrangler whoami

如果普通：

npx wrangler login

出现 callback 卡住，直接改用 --device。

---

Step 4：生成项目专用 API Token

在对应 Cloudflare Account 中创建只属于这个项目的 API Token。

原则：

只授权需要的 Account
只给 Worker / D1 / R2 等实际需要的权限
不要使用全局无限权限 Token

---

Step 5：项目 .env

CLOUDFLARE_ACCOUNT_ID=xxxxxxxx
CLOUDFLARE_API_TOKEN=xxxxxxxx

---

Step 6：wrangler.jsonc

{
  "name": "project-worker",
  "account_id": "xxxxxxxx"
}

---

Step 7：.gitignore

.env
.env.*
.dev.vars
.dev.vars.*

---

Step 8：验证

gh auth status

git config user.name
git config user.email
git remote -v

npx wrangler whoami

全部正确以后才：

git push
npx wrangler deploy

---

19. 日常开发 Loop

配置完成以后，日常应该非常简单。

cd project

开发：

npx wrangler dev

Git：

git status
git add .
git commit -m "feat: ..."
git push

Cloudflare：

npx wrangler deploy

正常情况下：

不需要重新登录 GitHub，不需要重新登录 Cloudflare，不需要切账号。

---

20. 给 Codex / Claude Code 的项目规则

可以在项目 AGENTS.md / CLAUDE.md 中写：

## Deployment Identity

This repository uses project-specific GitHub and Cloudflare credentials.

Rules:

1. Do not modify global GitHub authentication.
2. Do not run `gh auth switch` unless explicitly requested.
3. Do not run `wrangler login` or `wrangler logout` unless explicitly requested.
4. Use the repository's existing Git remote for Git operations.
5. Use the project's Cloudflare configuration and environment credentials.
6. Never commit `.env`, `.dev.vars`, API tokens, credentials, or secrets.
7. Before production deployment, verify the configured Cloudflare account.

核心思想：

Agent 使用环境，不管理环境。

---

21. 常见问题速查

Q1：gh auth login 会把旧 GitHub 账号删掉吗？

不会。

GitHub CLI 支持保存多个账号。

查看：

gh auth status

---

Q2：gh auth switch 是不是只影响当前终端？

不是。

它改变 GitHub CLI 的活动身份，因此不要把它当成 Terminal Session 隔离方案。

---

Q3：GitHub 多项目最重要检查什么？

git remote -v
git config user.name
git config user.email

---

Q4：npx wrangler login 网页成功但 CLI 卡死怎么办？

直接：

Ctrl+C
npx wrangler login --device

---

Q5：是不是梯子造成 Wrangler 登录失败？

不一定。

本次真实问题的关键在：

localhost:8976 OAuth callback

--device 不依赖这个 callback，因此更稳定。

---

Q6：npx wrangler auth login 对吗？

不对。

使用：

npx wrangler login

或者：

npx wrangler login --device

---

Q7：Wrangler Auth Profile 好不好？

设计上很好，而且就是为多账号目录隔离设计的。

但当前机器实际遇到：

auth create
→ localhost callback
→ CLI 卡死

所以目前不优先采用。

---

Q8：只在 wrangler.jsonc 写 account_id 就能多账号隔离吗？

不能完全做到。

还需要正确的：

认证身份 / API Token

---

Q9：真正最稳定的 Cloudflare 多项目方式是什么？

每个项目：

自己的 API Token
+
自己的 Account ID
+
自己的 wrangler.jsonc

---

Q10：旧项目要不要重新处理？

建议一次性给旧项目也补：

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID

完成后，以后基本不需要再管账号切换。

---

22. 最终推荐架构

Windows 本机
│
├── Project A
│   │
│   ├── Git
│   │   ├── Repository Remote A
│   │   └── Repository User A
│   │
│   └── Cloudflare
│       ├── API Token A
│       ├── Account ID A
│       └── Worker A
│
└── Project B
    │
    ├── Git
    │   ├── Repository Remote B
    │   └── Repository User B
    │
    └── Cloudflare
        ├── API Token B
        ├── Account ID B
        └── Worker B

日常：

进入哪个目录
        ↓
使用哪个项目的代码
        ↓
使用对应 Git 配置
        ↓
读取对应 Cloudflare 环境凭据
        ↓
部署对应项目

这就是最适合 CLI + Coding Agent + 多合作项目 的工作方式。

---

23. 一句话记忆

GitHub：固定 Repository + Git 身份；Cloudflare：固定 API Token + Account ID。账号属于项目，而不是属于当前 Terminal。

验证方法：

Goal: Verify Development Environment Is Ready

当前项目的 GitHub 与 Cloudflare 账号、CLI 和项目级配置已经完成。

本任务只做一件事：

验证当前项目开发环境是否已经完整打通，可以安全进入后续正式开发。

不要开发任何业务功能。

不要修改现有业务代码。

不要创建不必要的 Cloudflare 资源。

不要修改全局 GitHub / Cloudflare 登录配置。

---

1. Git / GitHub 验证

检查：

git status
git remote -v
git config user.name
git config user.email
gh auth status

确认：

• 当前目录是正确项目仓库
• origin 指向正确 GitHub Repo
• repository-local Git 用户名正确
• repository-local Git 邮箱正确
• GitHub CLI 已认证
• 当前账号具备访问该 Repository 的权限

然后执行一个只读远程测试：

git fetch --dry-run

如果适用，也可以：

gh repo view

要求确认：

当前项目可以正常访问对应 GitHub Repository。

不要为了测试而提交无意义 commit。

---

2. Node / Package Environment 验证

检查：

node --version
npm --version
npx wrangler --version

如果项目使用 pnpm：

pnpm --version

确认项目需要的 CLI 可以正常运行。

然后根据当前项目已有配置安装依赖：

pnpm install

或使用项目实际采用的 package manager。

不要擅自切换 package manager。

---

3. Cloudflare 身份验证

执行：

npx wrangler whoami

确认：

• Wrangler 可以正常认证
• 当前身份可以访问预期 Cloudflare Account
• Account ID 与当前项目配置一致

检查项目中的：

wrangler.jsonc
wrangler.toml
.env
.dev.vars

以实际存在的文件为准。

重点确认：

CLOUDFLARE_ACCOUNT_ID

或：

account_id

指向当前项目对应的 Cloudflare Account。

不要输出任何完整 API Token、Secret 或敏感凭据。

---

4. Cloudflare 配置验证

检查 Wrangler 配置是否合法。

如果当前项目已有 Worker：

执行：

npx wrangler deploy --dry-run

该命令只进行构建/打包验证，不真正部署。

确认：

• Wrangler 配置可以读取
• TypeScript / Worker 可以正常构建
• bindings 配置没有明显错误
• 不存在账号权限错误
• 不存在路径或入口文件错误

Cloudflare 官方支持 wrangler deploy --dry-run 用于在不真正部署的情况下验证 Worker 构建。

---

5. 项目 Build 验证

检查 package.json 中已有 scripts。

如果存在：

build
typecheck
lint
test

则按现有项目配置执行。

例如：

pnpm build
pnpm typecheck
pnpm lint
pnpm test

只执行项目已经定义的命令。

不要为了完成测试而自行大规模修改配置。

如果某一步失败：

1. 定位原因
2. 如果只是明显的环境配置问题，可以修复
3. 如果涉及业务代码或架构修改，不要擅自修改
4. 在最终报告中说明

---

6. Gitignore / Secret 安全检查

检查：

.gitignore

确保至少不会提交：

.env
.env.*
.dev.vars
.dev.vars.*
API Token
Secret
本地认证文件

检查：

git status

确认没有敏感文件处于 tracked / staged 状态。

不要打印 Secret 内容。

---

7. 最终验收报告

完成后输出一个简短报告：

# Environment Verification

## GitHub
- Repository: PASS / FAIL
- Git identity: PASS / FAIL
- GitHub authentication: PASS / FAIL
- Remote access: PASS / FAIL

## Local Toolchain
- Node: PASS / FAIL
- Package manager: PASS / FAIL
- Wrangler: PASS / FAIL
- Dependencies: PASS / FAIL

## Cloudflare
- Authentication: PASS / FAIL
- Correct Account ID: PASS / FAIL
- Wrangler config: PASS / FAIL
- Worker dry-run build: PASS / FAIL

## Project
- Build: PASS / FAIL
- Typecheck: PASS / FAIL / N/A
- Lint: PASS / FAIL / N/A
- Tests: PASS / FAIL / N/A

## Security
- Secrets excluded from Git: PASS / FAIL

## Final Result

READY FOR DEVELOPMENT

or

NOT READY

Blocking issues:
1. ...
2. ...

---

Definition of Done

只有以下条件全部满足，才可以给出：

READY FOR DEVELOPMENT

要求：

• GitHub Repo 可以访问
• Git remote 正确
• Git identity 正确
• Cloudflare 身份正确
• Cloudflare Account ID 正确
• Wrangler 可以正常运行
• Worker dry-run 可以通过
• 当前项目可以 build
• 没有 Secret 被 Git 跟踪
• 没有阻塞后续开发的环境错误

本任务结束后不要开始开发业务功能。

只报告环境是否已经达到：

可以直接进入下一阶段开发。