简介这是一份围绕全球最大代码托管平台GitHub与JavaScript开发的入门学习资料包适合正在学习版本控制、开源协作以及前端或Node.js开发的人群。压缩包共12个文件以HTML页面、JavaScript脚本为主辅以PNG图片和Git配置文件.gitattributes、.gitignore既可直接在浏览器中查看页面也能运行脚本体验交互还能了解规范的仓库配置。整个包仅229KB轻量便携目前已有2084人学习。内容将GitHub的核心机制——仓库、拉取请求、Issue、Actions、Pages等——与JavaScript在浏览器、Node.js、Electron等场景的应用结合起来通过示例文件帮助读者理解从代码托管到自动化部署的完整流程。同时覆盖Markdown文档写法、开源许可证选择、CI/CD工具集成等实用知识并包含创建仓库、发起Pull Request、编写Issue、配置Webhooks等关键操作要点是一份可随身查阅的GitHub与JavaScript实践清单尤其适合作为高校学生、转行开发者及开源爱好者的自学速查手册。1. 打开GitHub之前先搞清楚它到底帮你省什么你在本地改了三天代码想发给同事看看效果。压缩包发过去对方说“你第38行根本不是我看到的那一行”。这种场景我见过太多次技术上没什么大错但版本对不上、修改说不清、谁改了什么都无从追溯。GitHub解决的正是这件事把代码仓库放到一个固定的远程位置让每一次提交都有记录、可对比、能回滚也让多个人在同一份代码上协作时不至于互相覆盖。它既适合一个人写脚本的自由开发者也适合几十人一起交付软件产品的团队它既是备份也是协作入口更是代码审查、自动化检查和版本发布的控制台。这篇笔记按实际使用路径来讲仓库、分支、Pull Request、Issue、Actions这些对象各自解决什么问题、怎么组合使用、命令怎么写、出问题看哪里。读完你就能判断自己的项目要不要上GitHub以及上去了之后怎么走通第一条流程。2. 仓库、分支、PR、Issue把四个核心对象放进同一张工作台第一次用GitHub最容易犯的错是把它当成“网盘”。往上一传、覆盖保存、完事。GitHub和网盘的差别在于它保存的不只是最新一份文件而是完整的历史链条。这份历史链条由四个对象承载——仓库、分支、Pull Request、Issue。很多人上来就学命令但对这四个对象没有概念导致命令学完了也不知道什么时候该用哪个。这一章先把对象讲明白后面的命令才挂得住。2.1 仓库不只是存代码的地方远程备份与协作锚点仓库repository是GitHub上最基本的单位。一个仓库里装的是文件、目录、历史提交记录以及一堆看不见的配置。你在网页上看到的代码列表只是表面真正的仓库核心是隐藏的.git目录里面保存了所有提交对象、分支引用、配置项。我在团队里见过一个经典翻车现场有人把.git目录当垃圾删了代码文件还在但历史记录全没了——这意味着所有提交记录、分支、标签一起消失代码只能当新项目重新起头。远程仓库的核心价值有三个备份、协作、入口。备份指的是即使本地硬盘坏了远端仍保有完整历史协作指的是多人各自在本地提交再推送到同一远端通过合并把各自主线汇聚入口指的是GitHub会把代码审查、Issue、Actions、Release都挂在同一个仓库下让代码和配套信息在一起而不是散落在聊天记录和本地文件夹里。创建仓库的常见做法有三种。第一种是直接在GitHub网页上新建然后把本地项目推上去第二种是用GitHub CLI一步完成第三种是先在网页上建好空仓库再在本地git clone下来。推荐有命令行基础的人直接用GitHub CLIgh repo create my-project --public --clone cd my-project git commit --allow-empty -m chore: init repository git push -u origin main--public控制仓库可见性如果代码不能公开改成--private--clone表示创建后直接在本地克隆到当前目录--allow-empty创建一个空的初始提交方便后续分支操作。很多人会忽略这个空提交之前我也有段时间直接推送代码结果远端main分支在第一次推送前不存在后续一些工具扫描仓库时会报“分支不存在”的错。这个空提交就是给仓库一个稳定的起点。查看仓库与远端的关联状态我用git remote -v。它显示你配置了哪些远程地址正常情况至少有一个origin。如果输出为空说明之前是用git init在本地创建的仓库还没有和GitHub建立关联。如果以后要换仓库地址用git remote set-url origin 新地址不用删掉重加。提示仓库命名最好和项目名一致并且不要用中文和空格。仓库描述在网页上编辑写清楚“这是什么、语言、用途”对后续协作和检索都有帮助。2.2 分支与Pull Request从“我自己改”到“大家合改”的切换开关分支在Git里的本质是一个指向某个提交的指针。每次提交当前分支的指针往前移动一格。为什么需要分支因为它能隔离变更你在feature/add-login上改登录模块同事在fix/order-status上改订单状态互不影响。等到各自测试通过再把分支合并回main。没有分支的协作方式是所有人挤在一条主线上改谁先推谁后推全凭运气冲突几乎不可避免。Pull Request是GitHub在Git分支之上加的一层协作流程也是我认为最值得上GitHub的理由。它不仅是一份差异展示还自带讨论场所和合并闸门会给出改动对比、能逐行评论、能跑自动化检查、合并后还能自动关闭关联Issue。只做命令、不做PR的协作模式叫“裸分支推送”我在小团队里踩过坑。自己写还行人一多就乱没人知道某个改动是谁在什么时候为什么合进来的。标准流程是在一个功能分支上完成开发推送该分支到远端然后从浏览器发起Pull Request指定审查者等检查通过后合并。命令部分长这样git checkout -b feature/login # 修改代码 git add . git commit -m feat: add login API git push -u origin feature/login-b表示创建一个新分支并切过去。功能分支推上去后网页右上角会提示“Compare pull request”。PR标题我习惯写成“类型: 概述”比如fix: correct order status transition。这样git log和PR列表都能快速定位改动动机。合并时GitHub默认提供三种方式Merge commit保留完整历史Squash and merge合并成一个提交Rebase and merge改写为线性历史。个人项目我喜欢用Squash团队项目按规范来推荐Merge commit历史更真实。分支的生命周期也值得管理。功能分支合并后本地分支和远端分支都应该清理否则日积月累几十个死分支git branch -a拉出来一长串想找当前活跃的那条都费劲。删除本地已经合并的分支用git branch -d删远端分支用git push origin --delete branch-name。养成“合并即删除”的习惯仓库会保持干净。2.3 Issue与Project让需求、Bug和版本计划在同一条线上流通很多人不用Issue把需求都丢在即时通讯群里。群里聊完就沉底新同事来不了解前因后果。Issue的价值在于它是有编号的、可检索的、可关联代码的记录。Bug报告、功能建议、任务拆分都可以是一个Issue。每个Issue有自己独立的讨论区还能打标签、指派负责人、设定里程碑。和PR打通之后Issue的价值更大。我在提交信息里写fixes #12当这个PR合并进默认分支GitHub会自动关闭编号为12的Issue并把PR作为关联记录挂在Issue下面。这样后来者从Issue进入能直接看到谁修了、改了什么、讨论过程是什么。写功能时我习惯先开Issue再建分支在PR描述里标注对应Issue编号。这条链路跑顺之后再大的改动都能找到源头。git commit -m fix: validate email format before submit (fixes #12)fixes后面加Issue编号是GitHub的关键字约定。其他可以自动关闭Issue的关键字还有closes、resolves、fix。注意只有PR合入默认分支时才生效合入其他分支不会触发关闭。Project是把Issue摆到看板上。它的角色是轻量项目管理工具可以创建To do、In progress、Done等列把Issue按状态拖过去。对于没有专职项目经理的小团队这个看板足够用不用再跑到外部工具去维护第二份任务列表。要注意的是Project不是数据中心它对应的是“计划视图”。Issue可以同时属于一个Project和多个里程碑数据不重复。说个我观察到的现象小团队里Issue用得好不好往往决定了协作质量。Issue里留下的决策记录、失败尝试和验收标准比代码注释更值钱。代码注释说明“怎么做的”Issue说明“为什么要这么做”以及“尝试过哪些方案”。这层信息走IM会丢留在Issue里才是档案。开了仓库不建Issue等于断了一条回溯线索出了问题只能翻聊天记录效率极低。3. 用命令行把本地项目送上GitHub最小可用流程与参数避坑这一章是很多人的第一个动作把已存在的本地项目放到GitHub上。看似简单但认证方式、分支名、.gitignore、大文件任何一个没处理第一次推送就可能翻车。我按自己常用的一套流程拆开讲每一步失败时看什么报错也会一并说清。3.1 从git init到git push的完整命令首次推送的最小集合假设本地已经有一个项目目录里面代码能跑但还没用Git管理。完整命令如下cd /path/to/my-project git init git add . git commit -m Initial commit git branch -M main git remote add origin https://github.com/yourname/my-project.git git push -u origin main逐一说明。git init在当前目录初始化一个本地仓库生成.git目录。git add .把所有文件加入暂存区注意别急着执行——先确认.gitignore已经写好否则node_modules、构建产物、本地配置全会被提交进去这几个东西体积大、影响克隆速度还可能把密钥混进去。.gitignore写法不复杂每一行是一个忽略规则常见格式是node_modules/、dist/、.env。git commit生成本地第一个提交-m后面是提交信息。git branch -M main把当前分支改名为main。较早版本Git默认分支名是masterGitHub新建仓库默认是main。如果不改推送时远端可能产生两个不同名的分支后续协作混乱。git remote add origin把远端地址关联到本地名字用origin是惯例也叫默认远端。git push -u origin main首次推送-u把本地main和远端main建立追踪关系之后直接git push就能推不用再带参数。首次推送最容易碰到的报错有两个。第一是error: failed to push some refs通常因为本地和远端历史不相关——比如你在网页上建仓库时勾选了README初始化本地又是一个全新的init仓库两条历史没有共同点。解决方式有两种要么网页建仓库时不勾任何初始化文件要么先执行git pull --rebase origin main把远端内容合并进来再推送。第二是Authentication failed这是认证问题放在第四章详细讲。git add也不是只能全部暂存。只提交某个文件用git add path/to/file想只看哪些文件被改动用git status。我建议每次提交前都跑一遍git status和git diff确认改动的确实是这次要提的内容。这两个命令看不到历史看的是工作区当前状态不熟练的时候多跑几次不会出错。3.2 clone、remote与分支切换拿到别人的代码后怎么改参与别人项目的第一件事不是下载zip而是clone。zip只有当前快照没有历史和分支无法提交更新。clone会把整个仓库包括所有分支和历史提交都拉到本地git clone https://github.com/someone/project.git cd project git branch -a git checkout -b my-fix origin/maingit branch -a列出所有分支远端分支显示为remotes/origin/main。checkout -b my-fix origin/main表示基于远端main的最新代码创建本地分支my-fix。为什么不直接在main上改因为要在PR流程里让main保持干净直接从功能分支发起PR撤销和重来都容易。克隆时用的地址有两种协议HTTPS和SSH。HTTPS适合一次性只读简单SSH适合经常推送的开发者配置一次公钥后每次都不需要输入凭据。如果需要频繁推送我建议用SSH远程地址格式是gitgithub.com:someone/project.git。判断当前用的是哪种协议还是git remote -v输出里能看到开头是https://还是git。切换分支后最需要注意本地未提交的修改。如果你在main上改了文件还没提交直接checkout到别的分支改动会跟着你走或者Git拒绝切换报Your local changes would be overwritten by checkout。解决方案要么先commit要么stash。git stash把当前修改暂存起来切分支后git stash apply取回适合调试到一半需要紧急切到别的分支修Bug的场景。这个命令是后悔药比临时乱提交要干净得多。3.3 用工作流承接协作Fork、PR与Code Review的日常节奏参与开源项目、或者与不直接拥有你仓库权限的人协作典型路径是Fork。Fork是在GitHub上把别人的仓库复制一份到你的账号下然后你在副本上改改好了以Pull Request的形式把改动送回原仓库。这种模式的好处是原仓库的main分支完全不被污染审查者是唯一合流入口。git remote add upstream https://github.com/original/project.git git fetch upstream git checkout -b feature/fix origin/main git push -u origin feature/fix第一条添加upstream指向原仓库用于同步别人的新改动。fetch upstream把原仓库的最新提交下载到本地但不合并。基于最新代码创建分支推送后从网页发起PR。审查者在PR里逐行提意见你根据意见修改改完git commit --amend或者追加一个新提交都行追加提交更稳妥因为审查看得到“我根据你的意见做了什么修改”。PR合进main后把本地分支清理掉git checkout main git pull upstream main git branch -d feature/fix这里-d删除已合并分支。如果分支里有未合并的内容Git会拒绝删除要用-D强删但强删前先确认改动真的不要了。项目中我默认保留main、开发分支、以及当前迭代的功能分支三种。架构上不要开一堆命名混乱的临时分支每开一个分支前问自己这个改动是否必须独立于主线不是的话直接在主线提交。Code Review和PR的关系也要摆正。PR不是“对方拿走我的代码”而是“我请求对方帮我变更好”。PR描述里写清楚背景、改动点、测试结果审查者不用猜。逐行评论是GitHub最实用的机制它让意见直接挂在某一行代码上修改时能逐条定位。养成习惯后大部分问题在合入前就解决掉了。等代码进到主干再发现方向错了代价是返工重写而Review阶段发现方向错了只是改几行的事。4. GitHub日常使用的避坑排查从认证失败到合并冲突这一章是我被问得最多的部分。很多现象看着玄学其实就是一两个配置问题。按频率排序我把实战中最常见的五种给出排查路径每条按现象、原因、解决三步写。遇到问题别急着卸载重装先对照现象找原因。4.1 认证失败remote: Support for password authentication was removed现象使用git push时返回remote: Support for password authentication was removed或Authentication failed。原因GitHub于2021年停止支持用账号密码走HTTPS推送。密码认证被个人访问令牌Personal Access Token简称PAT取代。老旧配置里保存的还是密码或者根本没配过凭据就会出现这个报错。解决生成一个token并在推送时使用token作为密码。进入GitHub网页依次打开Settings - Developer settings - Personal access tokens - Tokens (classic)点Generate new token勾选repo权限复制生成的token。之后在命令行推送时提示输入密码粘贴token即可。更省事的方式是把它写入git凭据管理器git config --global credential.helper store git push # Username: 你的GitHub用户名 # Password: 粘贴token而不是账号密码credential.helper store把凭据明文保存到~/.git-credentials安全性低但方便适合个人开发机。团队环境建议用osxkeychain或manager-core由系统凭据库负责保管。还有一个我自己失误过的点我把token写进了被Git管理的文件里后来仓库公开token直接暴露只能紧急撤销重建。教训是token永远不要提交进仓库.gitignore里要写上包含token的文件名。4.2 大文件推不上去超过100MB的限制现象git push报remote: error: GH001: Large files detected...或者推到一半卡住不动。单个文件超过100MB时GitHub直接拒绝推送仓库总大小超过1GB会收到人工审核警告。原因二进制文件模型权重、安装包、构建产物被纳入了Git历史。Git对文本文件很友好但对二进制文件每个版本都完整保存一份体积迅速膨胀。很多人第一反应是“我删掉这个文件再提交一次就好”但历史提交里还保留着它GitHub扫描的是全部历史。解决需要从历史中抹掉该文件单靠删除当前版本不够。用git filter-repo重写历史pip install git-filter-repo git filter-repo --path path/to/large_file.zip --invert-paths git push origin --force --all--invert-paths表示“移除该路径”--force --all强制覆盖远端所有分支。注意这个操作会改写所有提交哈希所有协作者都需要重新克隆否则历史分叉。如果大文件必须保留唯一官方方案是Git LFS。Git LFS把大文件引用放在Git中实际内容存入LFS服务器但仓库的LFS配额有限超出要付费。经验之谈任何超过5MB的文件先想想能不能生成、下载、或放到对象存储里能就不要纳入Git历史。4.3 合并冲突为什么没改过的文件也会Conflict现象执行git merge或GitHub网页上点击合并时提示Conflicting files点进去却发现自己根本没碰过这个文件。原因冲突的判断标准不是“你是否改过”而是“是否有多个分支改动过同一位置”。你和对方都改过同一个文件虽然改的内容不同但Git无法自动确定以谁为准。比如两个人都在config.json里加了一个字段一个加在最前面一个加在最后面Git看上下文可能自动合并但如果加在同一位置附近就会冲突。看到冲突文件不是你改过的说明对方改过。解决两类办法。本地合并能看清冲突标记网页端解决适合改动比较小的场景。命令行方式git checkout main git pull origin main git checkout feature/xyz git merge main # 冲突文件出现在Unmerged paths手动编辑 git add conflicted_file git commit冲突文件里会有、、标记分别显示当前分支和对方分支的内容。手动选择保留哪段再git add。这些标记是给人看的绝对不能提交进仓库漏删会导致编译失败。Web端解决是进入PR页面Files changed找到冲突文件点Edit改完后Commit。我更建议本地解决因为可以看到上下文和测试结果网页编辑器里改容易丢失上下文。4.4 打不开或加载慢先分清是网络还是GitHub自身状态现象github.com在浏览器里转圈打不开命令行的git clone速度极慢甚至超时部分资源比如raw文件加载不到。原因这类现象基本有三个来源DNS解析失败或解析到了慢路径本地网络到GitHub的边缘节点不稳定GitHub自身服务故障。多数情况下不是GitHub崩了而是解析和连路的问题。最怕的是不看原因就乱改配置改了半天方向是错的。解决第一步先确认GitHub本身是否正常。打开GitHub Status页面看各个服务是否绿色。如果是全网故障只能等恢复本地折腾没有意义。第二步检查DNS解析nslookup github.com如果超时或返回异常IP尝试刷新本地DNS缓存。Windows执行ipconfig /flushdnsmacOS执行sudo dscacheutil -flushcacheLinux执行sudo systemd-resolve --flush-caches。然后把系统DNS改成公共DNS服务再重新nslookup。第三步如果DNS正常、GitHub服务也正常但对某些资源访问慢多数是个别域名的边缘节点问题。先测具体域名的连通性curl -I https://github.com看返回的HTTP状态码和时间。如果连通但慢说明慢在传输链路可以尝试在hosts文件里把相关域名指向更快返回的IP。注意直接改hosts要写对IPIP可以通过nslookup查多个解析结果再逐一测延迟。这一条建议配合真实测速结果去做不要照抄网上流传的hosts模板不同地区最佳IP不一样改错会导致完全连不上。我能给的判断标准是改完curl和git的耗时都明显下降才是有效配置。4.5 Actions跑了但没生效触发条件与权限的双重检查现象推了代码Actions页面没有触发新的workflow或者workflow运行了但一会儿就报Resource not accessible。原因第一类通常是触发条件写错。例如workflow里写的是on: push: paths: [src/**]但你改的是根目录文件自然不会触发。第二类通常是Token权限不足默认GITHUB_TOKEN权限只限于仓库本身如果想发布Release或修改Issue等操作需要额外开权限。解决先打开Actions选项卡确认workflow文件有没有被识别。文件必须放在.github/workflows/目录下后缀是.yml或.yaml。然后看workflow的on配置on: push: paths-ignore: - docs/** pull_request: types: [opened, synchronize]如果只想在push到main时运行写成on: push: branches: [main]。调试时故意加一个空提交触发一次验证git commit --allow-empty -m test workflow git push这是最常用的触发测试手段。权限问题去仓库Settings - Actions - General - Workflow permissions选择Read and write permissions保存后Re-run jobs。注意${{ secrets.MY_TOKEN }}的变量名必须在仓库Settings - Secrets里配置过否则运行时变量为空表现就是权限报错不是语法错误很容易看漏。5. 让GitHub替你干活自动化检查与版本发布的落地配置项目上了GitHub之后下一步是让重复的事自动完成。收益最大的三个配置Actions自动检查、Release发布、分支保护规则。它们直接决定协作质量和发布效率。5.1 用GitHub Actions做提交后的自动检查一个最小workflow每次push后自动跑测试和静态检查任何问题在合入前暴露。最底层的workflow文件如下name: CI on: push: branches: [main] pull_request: jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - run: npm teston里面写了两个触发源push到main以及任意PR。runs-on指定系统环境。actions/checkout是官方动作作用是拉取代码。setup-node配置Node版本cache: npm缓存依赖目录。npm ci是严格按锁文件安装保证CI环境与本地依赖一致npm test是测试命令按项目实际替换。Actions每次运行都是全新虚拟机你本地因为之前装过某些软件能跑CI里不会所以CI脚本要按“空环境能跑通”的最低要求来写。我在这上面撞过好几次本地调好的命令放到Actions里就因为缺环境变量或依赖失败。5.2 用Release与Tag规范版本发布版本号与发布说明的衔接Release把一个Tag指向某个commit附上说明和产物包。创建版本命令行先打Tag再推上去git tag v1.2.0 git push origin v1.2.0然后到仓库Release页面点击Draft a release选择这个Tag填写说明。版本号推荐遵循SemVer主版本号.次版本号.修订号。主版本号在不兼容API变化时递增次版本号在新特性时递增修订号在Bug修复时递增。发布说明列固定结构新特性、变更、Bug修复、已知问题。发布动作和CI联动是进阶玩法在main打Tag时自动生成Release但注意Actions对Release的写入权限要单独勾选Read and write否则会报权限不足。5.3 用分支保护规则拦截不该合入的代码设置路径仓库Settings - Branches - Branch protection rules。最值钱的组合是两条Require a pull request before merging Require status checks to pass。前者禁止直接push到main后者保证CI必须通过。加一条Require review from Code Owners可以把核心模块审核指定给专人方式是在仓库根目录放一个CODEOWNERS文件指定路径和负责人。我建仓库的第一天就设置保护规则不给自己留“先跑起来再说”的后路。这个习惯替我挡过至少三次差点把半成品发到线上的事件。当时觉得CI和审查拖慢速度现在是真香。GitHub这套东西的价值不是功能多而是“约定一旦固化为规则就不靠自觉”。希望帮到你。本文还有配套的精品资源点击获取