企业官网建设流程全解析

简介：这是一份围绕GitHub平台与JavaScript语言的轻量级前端示例资源，面向刚接触GitHub的开发者、Web前端初学者以及需要快速上手Git仓库协作的学生。压缩包提供了一个典型的GitHub托管项目结构，含多个HTML页面和JS脚本，可直观了解GitHub中仓库、版本控制、Issue、Actions等常见概念在源码层面的体现。资源共12个文件，以4个HTML、2个JS、2个PNG为主，HTML用于页面结构展示，JS负责交互与逻辑，PNG为界面或示意图片；另含.gitignore、.gitattributes等配置文件，完整展示了Git仓库的规范化写法，整体仅229KB，轻量便于下载阅读。预览显示资源内部按多个模块页面组织，各部分划分清晰，适合作为学习HTML与JavaScript项目搭建的参考模板。目前已有2084人学习过这份资料，读者可直接对照源码理解GitHub项目的组织方式，也可整理文件后作为自己的练习基础，快速建立前端开发与版本管理的基本认知。

1. GitHub 不是代码网盘：我们要用它解决的协作问题

GitHub这个名字，很多人第一次接触时把它当“代码网盘”——代码传上去，别人能下载，仅此而已。但真正用得起来的人知道，它最大的价值是围绕仓库长出来的协作机制：分支保护管住谁能改main，PR让每行代码都有审查记录，Issue把任务和提交串成可追溯的线，Actions把测试和发布变成自动流水线。这套机制解决的是一个具体痛点：多人改同一份代码，秩序从哪里来。如果你是3到10人的开发团队，或者维护一个长期项目，这篇笔记会带你把分支保护、PR审查、CI这三件最关键的机制从零搭起来，每一步为什么这样选、参数怎么设、哪里容易翻车，都会讲到。

2. 从零把仓库和分支保护搭起来：初始化命令与保护规则

仓库创建是整个协作流程的地基，但通常是被忽略得最狠的一步。很多人直接在网页上点几下就完事，后面分支保护、CI全凭记忆手动配，换台电脑又得重来。我习惯用 gh 命令行，把建仓库、忽略文件、许可证、README 一次配齐，还能直接把本地目录和远程仓库接好。这一章从初始化讲到给 main 上锁。

2.1 第一次建仓库：命令行初始化与本地关联

# 首次使用先登录 GitHub 账号 gh auth login # 建一个私有仓库，带 README、Git 忽略文件和 MIT 许可证 gh repo create demo-service --private \ --add-readme \ --add-gitignore=Node \ --license=MIT # 在已有项目目录里初始化并推到远程 git init git add . git commit -m "chore: initial commit" git remote add origin git@github.com:OWNER/demo-service.git git branch -M main git push -u origin main

gh repo create 会同时做两件事：在 GitHub 上生成远程仓库，并把当前目录和它关联好。--add-gitignore=Node 会按 Node 生态生成一份忽略文件，node_modules、日志、临时文件不会进仓库；--add-readme 和 --license=MIT 会创建两个基础文件，README 是仓库门面，LICENSE 决定别人能不能合法复用你的代码。这些参数一次配齐，比后期再补要省事得多。

--private 表示只有你能看到，适合业务代码；--public 适合打算开源的项目。git branch -M main 是把本地默认分支名改成 main，和 GitHub 新仓库的默认分支保持一致；git push -u origin main 里的 -u 会记住当前分支跟踪远程 main，以后直接 git push 即可。如果你已经有远程仓库，直接 git clone git@github.com:OWNER/REPO.git 拉下来更省事，它会把远程分支和已有提交全部带到本地，适合接手旧项目。

2.2 分支模型选型：别一上来就套 GitFlow

分支模型解决的是“什么时候新建分支、什么时候合回去”的秩序问题。业界常见的有两套：GitHub Flow 和 GitFlow，前者轻，后者重。

我的建议：大多数中小团队用 GitHub Flow 就够了。理由很简单：分支多了，合并和同步成本会指数上升；GitFlow 的 release 分支在你用 CI 自动发布时往往用不上。如果你的团队一开始只有两三个人，强行套 GitFlow，大部分精力会花在“这个提交合到哪”而不是“代码对不对”上。

# 从最新的 main 拉出功能分支 git checkout main git pull git checkout -b feat/user-login # 开发完成后推上去 git push -u origin feat/user-login

这里强调从最新的 main 拉分支，是为了让这条分支和主干差异尽量小，减小后面合并冲突的概率。git pull 拉的是远程 main 的更新，checkout -b 创建并切到新分支。分支名用“type/描述”的格式：feat 是新功能，fix 是修 bug，chore 是杂务。命名清晰，后面查历史、写 PR 标题都会省力。

2.3 给 main 上锁：分支保护规则与参数说明

分支保护是“PR 流程能成立”的前提。没有保护，大家说好的流程就会变成“我直接推一下就好，很快”，然后秩序崩掉。我一般在建仓库当天就把 main 保护写好，而不是等出了问题再补。

# 用 gh api 给 main 开启保护 gh api --method PUT repos/OWNER/REPO/branches/main/protection \ --input protection.json

protection.json 内容如下：

{ "required_status_checks": { "strict": true, "contexts": ["test"] }, "required_pull_request_reviews": { "required_approving_review_count": 1 }, "enforce_admins": true }

这段 JSON 是发送给 GitHub 分支保护接口的数据体，gh api 会把文件内容 POST 到保护端点完成配置。required_status_checks 表示 main 上的提交必须通过名为 test 的 CI 任务才能合并；strict: true 还要求分支在合并前已经和最新 main 同步过，防止静默覆盖别人的改动。required_pull_request_reviews 要求至少一个审查通过才能合。enforce_admins: true 连仓库管理员也要走流程，防止“我权限大我就直接推”的例外。

参数说明：contexts 里的 “test” 是 GitHub Actions 的 job 名称，需要在 CI 配置里保持一致；你后面加了 deploy job，就把 “deploy” 也加进数组。required_approving_review_count 可以设为 2 用于核心代码库，但团队小的时候 1 个足够，设太多会成为流程负担，大家会开始点“approve 但没真看”。

提示：网页上配置分支保护的路径是 Settings → Branches → Add rule，效果和 gh api 完全一致。但用 JSON 文件维护的优点是规则跟着仓库走，换电脑、换人维护都不会丢配置。

3. 用 PR 把代码审查变成常规动作：PR 模板、评审与合并策略

PR（Pull Request）是 GitHub 协作的核心动作，它把“我在本地写完代码”变成“我申请把这段改动合入主干，请你审查并决定是否接受”。但 PR 不是自动就能跑顺的。要把这套动作变成团队默认习惯，我一般做三件事：PR 模板写清楚、评审标准定下来、合并策略选对。下面展开。

3.1 把 PR 模板做好：让每条提交说明都完整

我通常会在仓库放一个 PR 模板，路径是 .github/PULL_REQUEST_TEMPLATE.md。模板的作用不是添麻烦，而是把“这次改了什么、为什么改、怎么验证”三个问题固定下来。没有模板的 PR 经常只有一个标题，reviewer 得翻代码才猜得出意图。

## 改动摘要 （用几句话说明这次要解决什么问题） ## 关联 Issue Fixes #___ ## 改动范围 - [ ] 前端页面 - [ ] 后端接口 - [ ] 数据库迁移 - [ ] 文档与配置 ## 测试计划 - [ ] 本地跑通 lint - [ ] 本地跑通单测 - [ ] 手动验证关键流程 ## 自检清单 - [ ] 无敏感信息（.env、密钥）入库 - [ ] 无依赖升级的破坏性变更 - [ ] 已更新相关文档

模板里的 “Fixes #12” 写法会在 PR 合并时自动关闭对应 Issue，把“代码”和“任务”串成一条线。改动范围的勾选项让 reviewer 一眼知道动了哪层，不用从头读代码猜改动面。自检清单的作用是让提交者先自查一遍，减少 reviewer 的低级检查——这条省下来的时间很可观。

参数说明：模板文件放在 .github/PULL_REQUEST_TEMPLATE.md，GitHub 会自动识别。如果仓库有多种 PR 类型，可以建多个模板放在 .github/PULL_REQUEST_TEMPLATE/ 目录，通过推送时的 query 参数选择；对中小团队，一个全局模板就够了。文件创建好后跟着代码提交推上去，和普通代码没有区别。

3.2 审查什么：评审清单与 gh pr review 实操

审查不必逐行读代码。我会按四层看：第一看变更和 PR 描述是否一致，防止夹带私货，顺手改了一堆无关代码；第二看边界条件有没有覆盖，比如空输入、超时、重复提交；第三看命名和结构是否和现有代码风格一致，不一致的地方提示，而不是强行要求重写；第四看涉及依赖和数据库变更时，兼容和回滚方案有没有想好。四层看完再决定 approve 还是 request changes。

# 查看某个 PR 的详情和变更内容 gh pr view 12 gh pr diff 12 # 提交评论意见 gh pr review 12 --comment --body "基础逻辑 OK，建议补一个空输入测试" # 通过审查 gh pr review 12 --approve # 要求修改 gh pr review 12 --request-changes --body "需要补充数据库回滚方案"

gh pr view 12 显示标题、状态、关联 Issue 和合并状态；gh pr diff 12 直接输出全部改动内容，适合在终端里快速过一遍再定意见。--comment 表示评论但不带倾向，--approve 表示通过，--request-changes 表示要求修改。三个动作要分开用，否则会变成人人都发一句 “LGTM” 但没有约束力。

参数说明：--body 是评论内容必填参数。命令行的操作和网页上的 “Review changes” 按钮是同一套动作，所有审查记录都会留在 PR 时间线里，后续回溯这个 PR 经历了什么，一目了然。

3.3 合并策略怎么选：squash、merge、rebase 对比

合并策略是很多团队忽略的坑，默认设置不一定适合你。GitHub 在合并 PR 时给三个选择，它们决定了 main 分支的历史长什么样。

我的默认选择是 squash。理由：功能分支上的几十个 “wip”“fix typo” 提交没有保留价值，压缩成一个 “feat: 实现用户登录”的提交，main 历史能让人一眼看明白这周做了什么。回滚也简单，git revert 一个提交就撤销整个功能。

# 用 squash 方式合并并删除远程分支 gh pr merge 12 --squash --delete-branch # 合并后悔了，回滚整个功能 git checkout main git pull git revert HEAD --no-edit git push

gh pr merge --squash 会把当前 PR 的所有提交压缩为一条进入 main。--delete-branch 顺手删掉已合并的远程分支，前端页面就不会堆满几百个残留分支。git revert HEAD 生成一个反向提交把改动撤销，它不会改写历史，其他已经拉过代码的人不会受到强制推送的影响——这是最稳妥的后悔药。

参数说明：--rebase 和 --merge 分别对应表中另外两种合并方式，按你选定的分支模型切换。git revert 后面也可以跟具体 commit hash，但在 squash 工作流下，revert HEAD 恰好对应整个功能，语义最干净。

4. 用 GitHub Actions 把验证和部署交给机器：最小 CI 与自动发布

CI/CD 是 GitHub 的价值放大器。之前合代码靠人提醒“记得跑测试、跑 lint”，有了 Actions，main 上任何风吹草动都会自动拉起验证流水线，合代码变成一件有机器兜底的事。这一章从最小可用的 CI 写起，写到缓存、任务编排和自动部署。所有配置都维护在仓库的 .github/workflows 目录下，改配置就是改代码，走同样的 PR 流程。

4.1 一个最小可用的 CI workflow：从 yaml 到首次跑通

name: CI on: push: branches: [main] pull_request: jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - run: npm ci - run: npm run lint - run: npm test - run: npm run build

workflow 文件必须放在 .github/workflows/ 目录下，文件名随意。on 定义触发条件：push 到 main 时跑一趟，所有 pull_request 事件也会跑——也就是说只要有人开出 PR，这条流水线就会自动出现提示。steps 是流水线里的每个动作：checkout 把代码拉进运行环境，setup-node 配好 Node 版本并启用 npm 缓存，后面的 run 依次执行装依赖、静态检查、单元测试、构建。

参数说明：runs-on: ubuntu-latest 是 GitHub 托管的虚拟环境，自带常用工具链；cache: 'npm' 会让 setup-node 自动缓存 npm 下载目录，CI 速度提升明显，依赖多的项目感受尤其深。node-version 建议和本地开发的主版本一致，否则本地能跑、CI 上因为版本差异翻车的情况会隔三差五出现。

4.2 缓存、依赖与任务编排：actions 参数进阶

jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - run: npm ci - run: npm run lint test: runs-on: ubuntu-latest needs: lint steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - run: npm ci - run: npm test deploy: needs: test if: github.ref == 'refs/heads/main' && github.event_name == 'push' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm ci - run: npm run build - run: echo "这里执行发布脚本"

把 lint 和 test 拆成两个 job，好处是失败点定位清楚：lint 挂了不会影响测试结果展示。needs: lint 表示 test 等 lint 跑完且通过后才启动，这是任务编排。deploy 用 needs: test 串联，确保验证全过才发布；if 条件限制了它只在 main 分支的 push 事件触发，普通 PR 时不会误触发布。

参数说明：github.ref 是 Actions 提供的上下文变量，refs/heads/main 代表 main 分支；github.event_name 判断触发事件是 push 还是 pull_request。两个条件配合的语义是“只有提交到了 main 才部署”。另外注意每个 job 都是独立虚拟机，需要重复 checkout 和 setup-node，缓存的意义正在于此：依赖下载只发生一次，后两个 job 直接命中缓存，省下的都是真实时间。

4.3 自动部署到服务器：把 CI 变成 CD 的一小步

deploy: needs: test if: github.ref == 'refs/heads/main' && github.event_name == 'push' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: 构建产物 run: npm ci && npm run build - name: 推送产物到服务器 env: SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} run: | mkdir -p ~/.ssh echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_ed25519 chmod 600 ~/.ssh/id_ed25519 scp -r dist user@examplehost:/var/www/demo ssh user@examplehost 'cd /var/www/demo && ./restart.sh'

发布的核心动作是：构建产物、把产物传上服务器、触发重启脚本。密钥通过仓库的 Secrets 注入环境变量，不会写死在 workflow 文件里。SSH_PRIVATE_KEY 是在仓库 Settings → Secrets and variables → Actions 里配置的密钥，Actions 运行时把它替换进 ${{ }} 位置。scp 传文件、ssh 远程执行命令，这是最朴素也最容易理解的发布方式。

参数说明：user@examplehost 换成你的服务器登录用户和地址。如果服务器只允许密钥登录，建议在仓库配置仓库级的 Deploy Key 而不是直接用某个人的个人密钥——个人密钥一旦离职要轮换，部署密钥只对该仓库生效，更安全。另外在 Settings → Actions → General 里把 Workflow permissions 选为 Read repository contents，把默认令牌权限收敛到最小化。

5. 绕开五个高频翻车点：GitHub 协作踩坑排查

工作流搭好之后，麻烦不会消失，只会换一种形式出现。下面五条是我在不同团队里反复见到的高频问题，每一条都按“现象、原因、解决”的顺序写。遇到问题时先对照这条清单，能省下不少翻聊天记录的时间。

5.1 大文件推不上云：100MB 限制不是开玩笑的

现象：git push 跑半天后报错 “this exceeds GitHub's file size limit of 100.00 MB”，本地一切正常，代码量也不大。

原因：把打包产物、数据文件或模型文件直接提交进了仓库，超过了 GitHub 单文件 100MB 的上限。这类文件体积大，且通常不该由 Git 管理。

解决：把不该进仓库的文件移出跟踪，并追加进 .gitignore：

git rm --cached build/output.zip echo "build/output.zip" >> .gitignore git commit -m "chore: stop tracking large artifact" git push

注意：如果这个文件已经存在于提交历史里，仅仅删掉当前版本不够，需要清理历史才算真正移除。我自己的习惯是 push 之前先 git status 看一眼暂存区有没有体积异常的文件，这个习惯帮我省掉过无数次被迫处理大文件的折腾。

5.2 PR 一直显示冲突：两个人改了同一段代码

现象：功能分支明明改动很小，PR 页面却显示 “This branch has conflicts that must be resolved”，合并按钮是灰的。

原因：main 从你拉分支之后往前走了，而且恰好改了你动过的区域。Git 不知道哪一版才是正确结果，所以把决定权交给你。

解决：把 main 的最新内容同步到你的分支：

git fetch origin main git merge origin/main # 解决冲突后 git add . git commit -m "merge: resolve conflict with main" git push

如果想把历史拉平，也可以把 merge 换成 rebase，但前提是这条分支没有和别人共享过。对新手来说 merge 更稳妥，看不懂 rebase 的交互过程时不要硬上。解决冲突时一定要看上下文，而不是机械地保留某一版，改完重新跑一遍相关测试——冲突解决本身就是一次小型开发，不是编辑文本。

5.3 Actions 里 npm ci 装不上依赖：本地和 CI 不一致

现象：CI 里 npm ci 频繁失败，报错说 package-lock.json 不存在或与 package.json 不同步，本地 npm install 却一切正常。

原因：lock 文件没有提交到仓库，或者 lock 文件过期没更新。npm ci 是精确安装模式，依赖 lock 文件做确定性安装，没有锁文件它直接拒绝工作。

解决：确认 package-lock.json 在 git 跟踪中；如果不同步，重新生成后提交：

git add package-lock.json git commit -m "chore: sync package lock" git push

这个问题的根源是把 lock 文件当成了“自己电脑上的东西”。lock 文件是团队的依赖契约，必须进仓库。用 npm install 临时替代 npm ci 会在团队人数上来后埋下隐患：每个人的依赖版本悄悄出现偏差，最后变成“我本地能跑”这种玄学问题。

5.4 密钥被提交进仓库：命中的不是代码而是事故

现象：某次提交把 .env 带上去了，几分钟后收到 GitHub 的密钥泄露告警邮件。

原因：手滑执行了 git add -A，暂存区里混入了带密钥的配置文件，而 .gitignore 里没把 .env 排除掉。

解决：第一步不是删文件，而是立刻去服务器把那个密钥作废并重新生成，然后才清理仓库：

git rm --cached .env echo ".env" >> .gitignore git commit -m "chore: stop tracking .env" git push

再强调一遍：密钥只要上了 GitHub，就等于公开了，删掉提交不代表安全，因为历史里还留着。唯一的后悔药是轮换密钥。养成把 .env、*.pem、credentials 这类文件写进 .gitignore 的习惯，比事后任何排查手段都省心。

5.5 有人绕过 PR 直接 push 到 main

现象：说好的流程跑了两个月，某天 main 上突然冒出一个没有经过 PR 的提交。

原因：分支保护规则没开 enforce_admins，或者当初设置时漏掉了有写权限的成员。

解决：用 gh api 检查保护是否真的生效：

gh api repos/OWNER/REPO/branches/main/protection

返回的 JSON 里确认有 "enforce_admins": true。如果之前是用网页设置的，再确认一下 “Include administrators” 复选框是勾上的。另外特别注意：当 main 上还没跑过 CI 时，开启 required_status_checks 会卡住接下来所有合并。正确的顺序是：先让一个普通 PR 完整跑通 CI，再开启保护规则，避免自己把自己锁在门外。

6. 让 GitHub 成为项目中枢：模板仓库与日常操盘技巧

前面五章把“仓库能用、协作顺、验证自动化”的骨架搭完了。这一章聊两个让我长期受益的习惯：模板仓库和 Issue 看板。

6.1 用模板仓库统一新项目的起点

仓库 Settings → General → Template repository，勾选这个选项后，仓库页面会出现 “Use this template” 按钮。点一下，GitHub 会把该仓库的目录结构、README、.gitignore、CI workflow、分支保护设置全部复制到新仓库。对需要开多个新服务的团队来说，这是统一工程规范最省力的方式——每个新服务一出生就自带同样的 lint、CI 和 PR 模板，不用从头配第二遍。

6.2 把 Issue、PR 和项目视图串成日常看板

在 .github/ISSUE_TEMPLATE/ 下放 bug_report.md 和 feature_request.md，让每个 Issue 自带版本号、复现步骤、预期行为；配合 Labels 打上 bug、enhancement、good first issue，Issue 列表就能充当团队的待办板。新版的 Projects 视图按状态分组展示 Issue 和 PR，PR 里写 “Fixes #12”，合并后自动关闭 Issue。这一串连起来，打开 Projects 页就能看清团队每个人在做什么。

# 列出最近一个月没有更新的 Issue，方便定期清理 gh issue list --state open --search "updated:<=2025-06-01" --limit 50

这里的 updated 是 GitHub 搜索限定符，日期替换成一个月前的日期即可；--search 是 gh issue list 传查询条件的参数。对中小团队来说，每月手动跑一次完全够用，没必要为这个专门写一套自动清理。

回看我自己的习惯，这些年建仓库的第一件事，永远是先把 main 保护规则写完，再写业务代码。早期不是这样——当时觉得团队就两三个人，走流程太麻烦，直到有一次模拟项目X 的 main 被直接推进去一个没测过的改动，线上出问题后翻查半天才定位到那次提交。从那以后我不再省这一步。GitHub 这套机制不复杂，但它是代码协作里成本最低的秩序投资：花二十分钟搭好，省掉的是一整年反复出现的合并冲突、审查缺失和发布事故。希望帮到你。

本文还有配套的精品资源，点击获取