简介：这份文档面向Web开发团队与项目管理人员，系统讲解Bitbucket在团队协作与项目管理中的实际应用，适合刚接触代码托管平台或希望从GitHub迁移的开发者参考。内容围绕Bitbucket的功能优势、与GitHub的差异、仓库创建与权限设置、代码托管流程展开，并配有创建仓库、推送代码、发起Pull Request等示例，帮助读者理解私有仓库免费、与Jira和Confluence深度集成、代码审查工具等核心特性。资源包共1个docx文件，约35KB，以图文教程形式组织，结构清晰，便于按章节查阅。已有64人学习下载，适合需要快速上手Bitbucket、搭建团队协作流程或对比主流托管平台的读者参考。
1. Bitbucket 团队协作：从 Git 本地提交到 Pull Request 合并的完整链路
很多团队用 Git 管代码，却卡在「怎么让五个人同时改一个仓库还不互相踩脚」这一步。Bitbucket 就是干这个的：它把 Git 仓库托管、分支权限、Pull Request 审查、流水线触发这几件事收在一个平台里。你本地git commit只是把改动存进自己的历史，真正让团队协作跑起来的是「推分支 → 开 PR → 审查 → 合并」这条链路。这篇笔记面向已经会基本 Git 命令、但没在 Bitbucket 上跑过完整协作流程的开发者，也适合想给团队定一套分支规范的技术负责人。下面从仓库初始化讲到 PR 合并策略，每一步都给可复现的命令和参数。
2. 仓库初始化与 SSH 认证：把本地 Git 和 Bitbucket 接上
2.1 为什么优先用 SSH 而不是 HTTPS
Bitbucket 支持 HTTPS 和 SSH 两种克隆方式。HTTPS 每次推送都要输账号密码（或者配凭据管理器），团队里一旦有人换了机器、清了凭据，就会反复弹认证框。SSH 用密钥对做认证，配一次长期有效，适合日常高频推送。常见做法是：个人开发机用 SSH，CI 流水线里用仓库级访问令牌（Access Token），因为流水线环境不方便挂个人私钥。
生成密钥对之前先确认本地有没有现成的：
ls -al ~/.ssh # 看有没有 id_ed25519 或 id_rsa，有就跳过生成步骤如果没有，生成一对 ed25519 密钥（比 RSA 更短更快）：
ssh-keygen -t ed25519 -C "your_email@company.com" # -t 指定算法，-C 是注释，一般写公司邮箱方便识别 # 一路回车即可，密码短语可以留空，也可以设一个生成后拿到公钥内容：
cat ~/.ssh/id_ed25519.pub # 输出以 ssh-ed25519 开头的一整行，全部复制把这一行贴进 Bitbucket 的「Personal settings → SSH keys → Add key」。注意公钥是一整行，复制时别漏掉末尾的邮箱注释，也别把私钥（没有 .pub 后缀的那个文件）贴上去。
2.2 验证连接与克隆仓库
配好公钥后先测连接，别急着克隆：
ssh -T git@bitbucket.org # 成功会返回类似 "logged in as your_username" 的提示 # 如果卡住或报 Permission denied，说明公钥没配对或没加到账号里连接通了再克隆。假设团队仓库地址是git@bitbucket.org:teamname/project.git：
git clone git@bitbucket.org:teamname/project.git cd project git remote -v # 确认 origin 指向的是 SSH 地址而不是 https 地址如果之前用 HTTPS 克隆过，可以改远程地址，不用重新克隆：
git remote set-url origin git@bitbucket.org:teamname/project.git这里有个高频翻车点：ssh -T报Permission denied (publickey)，九成是公钥没加对，或者本地有多个密钥、SSH 默认拿了错的那个。排查办法是加-v看握手过程：
ssh -vT git@bitbucket.org # 看输出里 "Offering public key" 那一行用的是哪个文件如果用的不是你想要的那个密钥，在~/.ssh/config里显式指定：
Host bitbucket.org HostName bitbucket.org User git IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yesIdentitiesOnly yes是关键，它强制只用指定的密钥，避免 SSH 挨个试导致认证失败。
2.3 全局配置与换行符处理
克隆完先检查 Git 身份配置，提交记录里的作者信息错了后面很难改：
git config --global user.name "Your Name" git config --global user.email "your_email@company.com" git config --list # 确认 user.name 和 user.email 生效跨平台团队（Windows + Mac/Linux 混合）一定要处理换行符，否则会出现「我只改了一行，diff 却显示整个文件都变了」的玄学问题。推荐统一策略：
# Windows 机器 git config --global core.autocrlf true # Mac / Linux 机器 git config --global core.autocrlf inputcore.autocrlf true表示提交时把 CRLF 转成 LF、检出时转回 CRLF；input表示提交时转 LF、检出时不转。这样仓库里存的永远是 LF，各平台本地各用各的。团队里如果有人没配，PR 的 diff 会很难看，审查时容易被误导。
3. 分支模型与 Pull Request：让多人改动不打架
3.1 选一套分支模型并写进团队约定
分支模型没有唯一正确答案，但团队必须统一。常见做法是主干开发 + 短生命周期特性分支：main保持随时可发布，每个需求从main切一个feature/xxx分支，做完开 PR 合回main。发布节奏慢的团队会用develop做集成分支，main只放已发布版本。选哪种取决于发布频率，不是取决于工具。
创建特性分支：
git checkout main git pull origin main # 先同步最新主干，避免从旧代码切分支 git checkout -b feature/user-login # 分支名带类型前缀，feature/ bugfix/ hotfix/ 一眼能看出用途分支名建议用「类型/简短描述」，别用test、dev、aaa这种。Bitbucket 的分支权限可以限制谁能直接推main，把main设成受保护分支后，所有改动必须走 PR，这是防止误推的最后一道闸。
3.2 提交、推送与开 PR 的完整命令
改完代码，提交时把改动拆成有意义的粒度：
git status # 先看改了哪些文件，别一股脑 git add . git add src/login.js src/auth.js # 只加本次相关的文件 git commit -m "feat: 增加用户登录接口" # 提交信息用「类型: 描述」格式，feat/fix/docs/refactor 等 git push -u origin feature/user-login # -u 把本地分支和远程分支关联，之后直接 git push 即可推送后 Bitbucket 页面会提示创建 Pull Request。PR 描述里写清楚三件事：改了什么、为什么改、怎么验证。审查者最怕看到「修复 bug」四个字，没有上下文根本没法审。
PR 的审查环节有几个必调设置：
| 设置项 | 建议值 | 作用 |
|---|---|---|
| 最少批准人数 | 1～2 | 防止自己合自己的代码 |
| 合并前必须解决评论 | 开启 | 避免审查意见被忽略 |
| 分支必须最新 | 开启 | 合并前强制同步主干，减少冲突 |
| 合并策略 | Squash 或 Merge commit | 决定历史是否保留每个提交 |
合并策略值得单独说。Squash 会把 PR 里所有提交压成一个，主干历史干净，但丢失中间过程；Merge commit 保留完整历史，但主干会多出合并节点。团队小、提交粒度乱的时候用 Squash；提交规范、想保留演进过程的用 Merge commit。这个选择要在建仓库时就定下来，中途改会让历史很乱。
3.3 用 PR 做代码审查而不是走过场
PR 的价值在审查，不在流程本身。审查时重点看逻辑边界、异常处理、命名和测试覆盖，别纠结空格和分号——那些交给格式化工具。Bitbucket 支持行内评论，评论时指明具体行和原因，比如「这里没处理空数组，会抛异常」，比「这里有问题」有用得多。
审查者本地拉取 PR 分支验证是个好习惯：
git fetch origin git checkout feature/user-login # 切到 PR 分支实际跑一遍，别只看 diff如果 PR 分支落后主干太多，先合并主干再继续：
git checkout feature/user-login git merge main # 解决冲突后提交，再推上去，PR 会自动更新冲突解决是新手最容易慌的环节。冲突标记<<<<<<<、=======、>>>>>>>之间是两边的改动，手动决定保留哪些，删掉标记，然后git add冲突文件、git commit。别用「随便选一边」的方式糊弄，冲突往往暴露了两个人改了同一块逻辑，需要沟通而不是硬合。
4. 避坑与排查：Bitbucket 协作里最常见的五类翻车
4.1 推送被拒：protected branch 或 non-fast-forward
现象：git push报remote: Permission denied或! [rejected] ... (non-fast-forward)。
原因有两种。一是推的是受保护分支（比如main），权限不允许直接推；二是本地分支落后远程，Git 拒绝覆盖。前者是权限设计，后者是本地没同步。
解决：受保护分支的改动走 PR，别硬推。落后导致的拒绝先拉再推：
git pull --rebase origin main # --rebase 把本地提交挪到远程最新提交之后，历史更线性 git push origin feature/user-login用--rebase而不是默认 merge，能避免多出一堆无意义的合并提交。但注意：已经推到远程、别人可能基于它工作的分支，不要随便 rebase，会改写历史。
4.2 SSH 认证失败但公钥明明加了
现象：ssh -T git@bitbucket.org报Permission denied (publickey)，但网页上确实加了公钥。
原因通常是本地有多个密钥，SSH 试了错的；或者公钥复制时多了换行、少了字符；或者~/.ssh权限太开放被 SSH 拒绝使用。
解决：先用ssh -vT看实际用了哪个密钥文件，再在~/.ssh/config里用IdentitiesOnly yes锁定。检查权限：
chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub权限不对时 SSH 会静默忽略密钥，这个坑很隐蔽。
4.3 大文件推送失败或仓库体积暴涨
现象：git push卡住或报pack exceeds maximum allowed size，或者仓库克隆越来越慢。
原因：把二进制文件、依赖包、构建产物提交进了 Git。Git 对文本友好，对大二进制文件会存多份历史，仓库迅速膨胀。
解决：用 Git LFS 管理大文件，或者干脆把构建产物加进.gitignore。已经提交的大文件要用git filter-repo清理历史，但这是重写历史，必须通知所有协作者重新克隆。预防永远比补救便宜：建仓库第一件事就是写好.gitignore。
4.4 .gitignore 不生效
现象：明明写了.gitignore，某个文件还是出现在git status里。
原因：文件在写.gitignore之前已经被跟踪了，Git 不会自动忽略已跟踪文件。
解决：先从索引里移除，再提交：
git rm --cached config/local.env # --cached 只从索引移除，不删本地文件 git commit -m "chore: 停止跟踪本地配置"注意git rm --cached不会删你本地的文件，只是让 Git 不再跟踪它。团队里每个人都要做一次，或者把这个操作写进初始化脚本。
4.5 PR 合并后主干构建失败
现象：PR 单独测都过，合并到main后流水线挂了。
原因：两个 PR 各自没问题，但合在一起产生冲突——比如一个改了函数签名，另一个还在用旧签名调用。PR 审查时各自看 diff 看不出来。
解决：开启「分支必须最新」设置，强制 PR 合并前同步主干；同时让 CI 在 PR 分支上跑完整构建，而不是只跑增量。合并前本地也拉一次主干验证：
git checkout main git pull origin main git checkout feature/xxx git rebase main # 在最新主干上重跑测试，通过再合5. 用分支权限和流水线把协作规范固化下来
前面讲的都是「人自觉」，但团队一大，规范必须靠工具强制。Bitbucket 的分支权限（Branch permissions）能限制谁能推、谁能合、谁能删分支。常见配置是：main只允许通过 PR 合并，禁止直接推；release/*只允许发布负责人操作；feature/*放开给开发者。这样即使有人手滑git push origin main，也会被服务端拒绝。
再进一步是流水线。Bitbucket Pipelines 用仓库根目录的bitbucket-pipelines.yml定义构建步骤，PR 创建和更新时自动触发：
pipelines: pull-requests: '**': - step: name: 构建与测试 image: node:20 script: - npm ci - npm run lint - npm testpull-requests下的'**'表示对所有目标分支的 PR 生效。npm ci比npm install更适合 CI，它严格按 lock 文件安装，保证环境一致。把 lint 和 test 放进 PR 流水线，审查者就不用人工检查代码风格，机器能拦的问题不占用人的时间。
流水线跑通后，把「PR 必须通过流水线才能合并」打开，规范就从「建议」变成了「强制」。这一步做完，团队协作的底线就守住了：主干永远可构建，合并必须过审查，历史可追溯。
我自己踩过最深的坑，是早期图省事让所有人直接推main，结果某次有人推了半成品，发布当天回滚了两次。后来把main锁死、强制 PR、强制流水线，回滚次数直接归零。规范不是给新人添麻烦，是给所有人留后悔药。希望帮到你。
本文还有配套的精品资源，点击获取
