简介本资源是一份面向JavaScript初学者与Web开发入门者的GitHub平台实践入门包聚焦代码托管、协作开发与基础工程化能力培养。压缩包共12个文件含4个HTML页面用于展示项目结构与说明、2个JS脚本体现前端交互逻辑、2个PNG图像可能为界面示意图或流程图、2个.DS_Store系统文件Mac目录元数据可忽略以及.gitattributes和.gitignore配置文件完整呈现典型GitHub仓库的初始化结构总大小仅229KB轻量易解压学习。已有2084人下载学习适合零基础了解Git工作流、Pull Request协作、README文档编写及GitHub Pages部署等核心实践环节。资源虽小但结构规范涵盖版本控制配置、静态页面组织、开源项目标准文件如许可证与贡献指南的占位示意是理解现代前端项目托管与社区协作模式的理想起点。1. GitHub 不是代码托管网站那么简单它是一套可落地的协作操作系统工程师每天用它做需求拆解、版本回溯、CI 验证和知识沉淀很多人第一次接触 GitHub是被“开源项目托管平台”这个标签框住的——以为它只是放.git仓库的地方。但真实场景里我见过某高校实验室用 GitHub Issues 拆解一个图像配准模块的 37 个子任务用 Projects 看板实时同步 FPGA 与算法组的接口对齐进度也见过某公司把 PR 描述模板固化成 checklist强制每次合入前验证 CUDA 版本兼容性、ONNX 导出精度误差、Docker 构建耗时三道关卡。GitHub 的核心价值不在“存代码”而在“让多人协同过程可追溯、可验证、可复现”。它天然适配 Python/JavaScript/C 多语言混合项目尤其当团队里有前端依赖 npm/yarn、后端依赖 Maven/Gradle、嵌入式依赖 CMake三类角色时GitHub Actions 能统一调度不同环境的构建流水线。如果你正在带一个 38 人的技术小组做课程设计、毕业设计或轻量级产品原型又不想搭 Jenkins、维护 GitLab RunnerGitHub 就是那个“开箱即用但深度够挖”的协作基座。它不解决算法本身但能让你花在扯皮、找错、重装环境上的时间减少 60% 以上。2. 从零初始化一个工程级仓库结构设计、分支策略与 .gitignore 实战配置2.1 为什么你的仓库第一天就该规划好 src/docs/scripts 目录层级新手常犯的错误是git init后直接往根目录塞.py文件、requirements.txt和README.md结果两周后发现模型权重文件误提交、本地调试日志污染历史、Jupyter Notebook 输出缓存导致 diff 失效。一个工程级仓库必须在初始化阶段就建立物理隔离。我一般会按如下结构创建my-vision-project/ ├── src/ # 所有可执行源码Python/JS/C │ ├── core/ # 核心算法模块YOLO 推理、Transformer 编码器 │ ├── utils/ # 通用工具文件读写、日志封装、CUDA 设备管理 │ └── cli.py # 命令行入口避免直接运行 notebook ├── notebooks/ # Jupyter 实验记录禁止含 output用 nbstripout 过滤 ├── data/ # 符号链接到外部存储绝不放原始数据进 git │ └── raw/ # 指向 /mnt/nas/dataset/voc2012 的软链 ├── models/ # 训练产出.pt/.onnx/.h5设为 git-lfs 跟踪 ├── docs/ # Sphinx 生成的 API 文档源码 ├── scripts/ # 一键部署/数据预处理/环境校验脚本bash python 混合 ├── tests/ # pytest 用例覆盖核心函数输入输出边界 ├── .github/ # GitHub 专属配置Actions 工作流、ISSUE 模板 ├── pyproject.toml # 统一依赖管理替代 setup.py requirements.txt └── README.md # 用 Mermaid 画架构图 三步快速启动命令提示data/下所有子目录必须用ln -s指向外部路径Git 只跟踪软链接文件本身。这样既保证仓库轻量又避免同事 clone 后因缺数据而报错。2.2 分支策略不是教条基于交付节奏选 trunk-based development 或 git-flow 变体你不需要死守“master 是稳定版、develop 是集成版”这种老派规则。实际中我根据项目生命周期动态切换课程设计/4 周内交付原型用单分支main 标签tag管理里程碑。每次 commit 前跑pytest tests/ --tbshort失败则禁止 push。用git tag v0.1.0 -m 支持 VOC 格式加载标记可演示节点。毕业设计/3 个月迭代启用main生产就绪dev集成测试双分支。所有功能开发从dev拉新分支如feat/yolo-v8-export合并前必须通过 GitHub Actions 的 lint test build 三阶段检查。长期维护的工具库采用 trunk-based developmentTBD取消长期功能分支。所有修改直接向main提 PR但强制要求PR 标题含[WIP]或[READY]状态标识描述区粘贴pre-commit run --all-files输出关联至少一个 Issue如Closes #23。关键不是分支名而是每个分支背后绑定的自动化门禁。比如dev分支的推送会触发build-docker-image.yml而main分支的 merge 会触发publish-pypi.yml—— 这些才是真实约束力。2.3 .gitignore 必须手写不能靠在线生成器JavaScript 项目特有陷阱JavaScript 生态的临时文件比 Python 更隐蔽。以下是我从某跨平台系统实战中总结的.gitignore核心段落已剔除通用模板只留 JS 项目高频踩坑项# Node.js 构建产物比 node_modules 更危险的是这些 dist/ build/ out/ .next/ .nuxt/ # TypeScript 编译残留即使你用 tsc --noEmitwatch 模式仍会生成 *.js.map *.d.ts # 包管理器元数据yarn.lock/npm-shrinkwrap.json 二选一保留 yarn.lock # 但禁止提交 pnpm-lock.yaml错pnpm 用户必须提交它否则 workspace 依赖解析失败 pnpm-lock.yaml # VS Code 调试配置launch.json 含本地路径绝对不能进仓库 .vscode/launch.json # 浏览器 DevTools 保存的断点Chrome 会自动生成 *.breakpoints.json # Cypress E2E 测试的视频与截图体积大且含敏感路径 cypress/videos/ cypress/screenshots/ # 最关键不要忽略 .env但要忽略 .env.local本地密钥 .env !.env.example # 示例文件必须提交供新人复制修改注意.env行末的!.env.example是白名单语法表示“忽略所有.env*但.env.example除外”。很多团队因漏写这行导致新人 clone 后找不到环境变量模板硬编码密钥进代码——这是安全审计的高危项。3. GitHub Actions 自动化流水线用 YAML 写出可调试的 CI/CD而非黑匣子3.1 为什么 80% 的 Actions 失败源于 job 间环境隔离失效GitHub Actions 默认每个 job 运行在全新虚拟机上这意味着npm install在 build job 装的包test job 里根本不存在。新手常写# ❌ 错误示范假设依赖全局安装 jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: npm ci - run: npm run build test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: npm test # 此处 npm 未安装直接报 command not found正确做法是用actions/cachev4缓存node_modules并显式声明 cache key# ✅ 正确用 package-lock.json 内容哈希作为缓存键 jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Cache node_modules uses: actions/cachev4 with: path: node_modules key: ${{ runner.os }}-node-${{ hashFiles(**/package-lock.json) }} - name: Install dependencies run: npm ci - name: Build run: npm run build test: needs: build runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Cache node_modules uses: actions/cachev4 with: path: node_modules key: ${{ runner.os }}-node-${{ hashFiles(**/package-lock.json) }} - name: Install dependencies run: npm ci - name: Run tests run: npm test逻辑说明hashFiles(**/package-lock.json)会计算所有 lock 文件内容的 SHA256只要依赖没变缓存 key 就一致test job 就能复用 build job 的node_modules。参数path: node_modules指定缓存目录runner.os避免 macOS 与 Linux 缓存混用。3.2 JavaScript 单元测试必须带覆盖率上传用 nyc codecov 实现质量门禁仅跑npm test不够必须量化“测得全不全”。我用nycistanbul注入覆盖率收集再推送到 Codecov- name: Test with coverage run: npx nyc --reportertext --reporterlcov npm test - name: Upload coverage to Codecov uses: codecov/codecov-actionv3 with: token: ${{ secrets.CODECOV_TOKEN }} # 在仓库 Settings Secrets 中配置 file: ./coverage/lcov.info flags: unittests name: codecov-umbrella关键参数说明--reportertext在 Actions 日志中打印终端覆盖率报告如Statements : 85.2%--reporterlcov生成coverage/lcov.info供 Codecov 解析flags: unittests标记此上传属于单元测试维度便于后续按测试类型分层分析。注意nyc必须在package.json的scripts.test中前置例如test: nyc --silent mocha test/**/*.spec.js。若用 Jest直接jest --coverage即可无需 nyc。3.3 避坑JavaScript 项目 CI 常见问题排查清单现象原因解决npm ci报错Cannot find module typescriptpackage.json中devDependencies缺少typescript但tsconfig.json存在导致nyc启动时尝试加载 TS 编译器在devDependencies中显式添加typescript: ^5.0.0并确保tsc --version在 Actions 中可执行Cypress E2E 测试在 CI 中白屏GitHub Actions 默认浏览器无 GPU 加速且未设置--headlessnew参数在cypress.yml中添加env: CYPRESS_VIDEO: false和CYPRESS_BROWSER: chrome并在run步骤加--browser chrome --headless --no-sandbox --disable-gpunyc覆盖率报告始终为 0%源码使用 ES Module 语法import/export但nyc默认不处理.mjs文件在.nycrc中添加extension: [.js, .cjs, .mjs]并设置require: [esm]npm publish失败提示401 UnauthorizedNPM_TOKENsecret 未在仓库 Settings Secrets 中配置或 token 权限不足需勾选Automation进入 npmjs.com → Account → Tokens → Generate new token → Type 选Automation→ 复制后粘贴到 GitHub Secretskey 命名为NPM_TOKEN4. Issue 与 Pull Request 的工程化用法把需求、缺陷、评审变成可追踪的数据资产4.1 Issue 模板不是形式主义用 YAML 定义结构化字段驱动自动化分类GitHub 支持 YAML 格式的 Issue 模板这能让“新增功能”“修复 Bug”“文档改进”自动打标并路由到对应负责人。例如.github/ISSUE_TEMPLATE/feature_request.ymlname: 新增功能 about: 提出一个新特性需求 title: [Feature] labels: [enhancement, triage] assignees: [developer-a] # 自动分配给 A 同学初审 body: - type: input id: impact attributes: label: 影响范围影响几个模块 description: 例如仅影响 src/utils/logger.js或涉及 src/core/ 与 tests/ validations: required: true - type: dropdown id: priority attributes: label: 优先级 options: - P0阻塞发布 - P1本周内需排期 - P2下月迭代 - type: textarea id: use-case attributes: label: 典型使用场景请描述用户操作流程 description: 例如“用户上传图片 → 点击‘增强’按钮 → 页面显示处理后图像” placeholder: | 1. 用户在 Web 界面选择一张 JPEG 图片 2. 点击「超分」按钮 3. 前端调用 /api/super-res API 4. 返回 base64 图像并渲染效果当用户填写此模板提交 IssueGitHub 自动生成带impact、priority字段的 issue并自动打上enhancement标签。后续可用 GitHub Search 过滤label:enhancement priority:P0快速定位高优需求。4.2 PR 描述必须含可验证的验收标准拒绝“已修复”这类玄学表述PR 描述是代码变更的契约。我强制要求每份 PR 描述包含## 验收标准区块且每条标准必须可执行、可观测## 验收标准 - [x] npm run build 成功生成 dist/bundle.js文件大小 ≤ 120 KB原为 145 KB - [x] 在 Chrome 120、Firefox 115 中打开 http://localhost:3000/demo点击「导出 ONNX」按钮后控制台无 TypeError 报错 - [x] 运行 npm test -- --testPathPatternonnx-export.spec.js全部 5 个用例通过 - [ ] 待测在 NVIDIA T4 GPU 上运行 python scripts/test_onnx_inference.py --model dist/model.onnxFPS ≥ 23提示带[ ]的条目表示尚未验证合并前必须打钩。这种写法倒逼开发者在提 PR 前完成本地验证而不是把测试甩给 CI。4.3 利用 GitHub Projects 看板实现需求穿透从 Issue 到代码再到部署状态Projects 看板不是 To-do List而是状态机。我为某图像处理 Demo 配置了四列列名触发条件自动化动作BacklogIssue 创建且无triage标签GitHub Action 自动添加triage标签In ProgressIssue 被 assignee 接收或 PR 关联该 Issue当 PR 的 title 含Closes #123自动将 #123 移入此列Review ReadyPR 通过所有 CI 检查且有 ≥2 个 approve用pull-request-approval-action检测 approve 数达标后移动卡片DonePR 合并到main分支GitHub webhook 监听pull_request.closed事件自动归档关键技巧每张卡片右上角显示Status: deployed或Status: pending CI这是用 GitHub API 查询 Actions 运行状态后动态更新的。这样产品经理刷看板时一眼就能看出“用户登录优化”这个需求是否已上线。5. JavaScript 项目的安全加固从依赖扫描到 SCA绕过 npm audit 的认知陷阱5.1npm audit是过时方案用snyk test替代精准定位供应链风险npm audit仅检查package-lock.json中的直接依赖对 transitive dependency传递依赖漏报严重。例如lodash的prototype pollution漏洞可能藏在webpack - terser - acorn链路中npm audit无法告警。我改用 Snyk CLI# 安装并认证token 在 snyk.io 获取 npm install -g snyk snyk auth # 扫描项目生成 HTML 报告 snyk test --filepackage-lock.json --severity-thresholdhigh --json snyk-report.json snyk monitor # 上传到 Snyk 云平台持续跟踪新漏洞Snyk 的优势在于基于真实 exploit 数据库而非 CVE 静态匹配显示漏洞影响路径如acorn7.4.0 ← terser5.16.0 ← webpack5.88.0提供snyk wizard交互式升级建议自动修改package.json。注意--severity-thresholdhigh表示只报告 high/critical 级别漏洞避免低危告警淹没有效信息。5.2 防御恶意包投毒用lockfile-lint强制校验 package-lock.json 完整性2023 年多起 npm 包投毒事件源于攻击者篡改package-lock.json中的resolved字段指向恶意镜像。lockfile-lint可在校验阶段拦截npm install --save-dev lockfile-lint在.lockfile-lintrc.json中配置{ allowedHosts: [registry.npmjs.org, github.com], allowedSchemes: [https:, githttps:], enforceTopLevelDependency: true, allowedIntegrityAlgorithms: [sha512, sha384] }然后在 CI 中加入步骤- name: Validate lockfile run: npx lockfile-lint --type npm --path package-lock.json参数说明allowedHosts只允许从官方 registry 或 GitHub 拉取包enforceTopLevelDependency禁止package-lock.json中出现未在package.json声明的顶层依赖防postinstall脚本偷偷装包allowedIntegrityAlgorithms强制使用强哈希算法拒绝sha1已被破解。5.3 避坑JavaScript 依赖安全常见误区与真相误区真相行动建议“只要npm update就安全”npm update只升到package.json中^或~允许的最高版本可能跳过含漏洞的中间版本改用npm outdated查看可升级列表再手动npm install lodash4.17.21指定修复版本“私有 registry 就绝对安全”私有 registry 若未开启audit代理或缓存污染防护仍可能同步恶意包在私有 registry如 Verdaccio配置security插件启用snyk或ossindex实时扫描“TypeScript 能防止运行时漏洞”TS 仅做编译期类型检查对原型链污染、正则 DoS、HTTP header 注入等完全无效必须配合snyk testeslint-plugin-security检查eval()、new Function()等危险 API“忽略 devDependencies 的漏洞”devDependencies中的webpack-dev-server若含 XSS 漏洞本地开发时浏览器访问localhost:8080即被攻击在snyk test中移除--dev参数全量扫描所有依赖6. 从“能跑通”到“可交付”用 GitHub Release GitHub Pages 构建最小可行交付物6.1 Release 不是打标签用 GitHub Actions 自动生成 changelog 与二进制包Release 页面是用户第一眼看到的交付物。我拒绝手写v1.2.0更新日志而是用conventional-commits规范提交信息再由standard-version自动生成# 安装并初始化 npm install --save-dev standard-version npx standard-version --init约定提交前缀feat:新功能触发 minor 版本fix:修复 bug触发 patch 版本docs:文档变更不触发版本号chore:构建脚本修改不触发版本号然后在.github/workflows/release.yml中on: push: tags: - v[0-9].[0-9].[0-9] # 匹配 v1.2.0 格式 tag jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 # 必须获取全部 commit 历史 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 18 - name: Install dependencies run: npm ci - name: Generate changelog and publish run: npx standard-version --skip.commit --skip.tag env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}效果当执行git tag v1.2.0 git push origin v1.2.0Actions 自动解析feat:/fix:提交生成CHANGELOG.md打包dist/下的bundle.js与index.html为my-app-v1.2.0.zip创建 Release 页面附带下载链接与版本差异Compare v1.1.0...v1.2.0。6.2 GitHub Pages 不只是静态站用gh-pages发布可交互的 JavaScript DemoGitHub Pages 常被当作文档托管但它能直接运行前端应用。以一个 YOLOv8 Web Demo 为例# 安装 gh-pages npm install --save-dev gh-pages在package.json中添加脚本scripts: { deploy: gh-pages -d dist -b gh-pages -r https://github.com/username/my-vision-project.git }dist/目录结构需满足dist/ ├── index.html # 入口页含 script srcbundle.js/script ├── bundle.js # Webpack 打包产物含模型权重 base64 编码 ├── assets/ # 图片、字体等静态资源 └── manifest.json # PWA 配置可选关键配置在webpack.config.js中设置output.publicPath: /否则bundle.js加载路径会错。部署后访问https://username.github.io/my-vision-project/即可在线体验无需任何服务器。6.3 验证交付物完整性的终极 checklist我每次发布前必跑的 5 项验证少一项都不点 Merge验证项命令/操作通过标准1. 构建产物完整性unzip -l my-app-v1.2.0.zip | grep -E \.(js|html|css)$列出所有 JS/HTML/CSS 文件确认无缺失2. 浏览器兼容性在 BrowserStack 中打开https://username.github.io/my-vision-project/测试 Chrome/Firefox/Safari 最新版页面渲染正常控制台无Uncaught SyntaxError3. 离线可用性断网后刷新页面检查 Service Worker 是否激活Application → Service Workers显示Status: activated且index.html可离线加载4. 安全头信息curl -I https://username.github.io/my-vision-project/响应头含Content-Security-Policy: default-src self5. Lighthouse 性能分Chrome DevTools → Lighthouse → Mobile → Generate reportPerformance ≥ 85Accessibility ≥ 90SEO ≥ 95从那以后我每次发布 Release都强制走一遍这个 checklist —— 不是因为信不过 CI而是因为真实用户用的不是 Ubuntu runner而是带着各种插件、旧版浏览器、弱网环境的 Chrome。希望帮到你。本文还有配套的精品资源点击获取
简介本资源是一份面向JavaScript初学者与Web开发入门者的GitHub平台实践入门包聚焦代码托管、协作开发与基础工程化能力培养。压缩包共12个文件含4个HTML页面用于展示项目结构与说明、2个JS脚本体现前端交互逻辑、2个PNG图像可能为界面示意图或流程图、2个.DS_Store系统文件Mac目录元数据可忽略以及.gitattributes和.gitignore配置文件完整呈现典型GitHub仓库的初始化结构总大小仅229KB轻量易解压学习。已有2084人下载学习适合零基础了解Git工作流、Pull Request协作、README文档编写及GitHub Pages部署等核心实践环节。资源虽小但结构规范涵盖版本控制配置、静态页面组织、开源项目标准文件如许可证与贡献指南的占位示意是理解现代前端项目托管与社区协作模式的理想起点。1. GitHub 不是代码托管网站那么简单它是一套可落地的协作操作系统工程师每天用它做需求拆解、版本回溯、CI 验证和知识沉淀很多人第一次接触 GitHub是被“开源项目托管平台”这个标签框住的——以为它只是放.git仓库的地方。但真实场景里我见过某高校实验室用 GitHub Issues 拆解一个图像配准模块的 37 个子任务用 Projects 看板实时同步 FPGA 与算法组的接口对齐进度也见过某公司把 PR 描述模板固化成 checklist强制每次合入前验证 CUDA 版本兼容性、ONNX 导出精度误差、Docker 构建耗时三道关卡。GitHub 的核心价值不在“存代码”而在“让多人协同过程可追溯、可验证、可复现”。它天然适配 Python/JavaScript/C 多语言混合项目尤其当团队里有前端依赖 npm/yarn、后端依赖 Maven/Gradle、嵌入式依赖 CMake三类角色时GitHub Actions 能统一调度不同环境的构建流水线。如果你正在带一个 38 人的技术小组做课程设计、毕业设计或轻量级产品原型又不想搭 Jenkins、维护 GitLab RunnerGitHub 就是那个“开箱即用但深度够挖”的协作基座。它不解决算法本身但能让你花在扯皮、找错、重装环境上的时间减少 60% 以上。2. 从零初始化一个工程级仓库结构设计、分支策略与 .gitignore 实战配置2.1 为什么你的仓库第一天就该规划好 src/docs/scripts 目录层级新手常犯的错误是git init后直接往根目录塞.py文件、requirements.txt和README.md结果两周后发现模型权重文件误提交、本地调试日志污染历史、Jupyter Notebook 输出缓存导致 diff 失效。一个工程级仓库必须在初始化阶段就建立物理隔离。我一般会按如下结构创建my-vision-project/ ├── src/ # 所有可执行源码Python/JS/C │ ├── core/ # 核心算法模块YOLO 推理、Transformer 编码器 │ ├── utils/ # 通用工具文件读写、日志封装、CUDA 设备管理 │ └── cli.py # 命令行入口避免直接运行 notebook ├── notebooks/ # Jupyter 实验记录禁止含 output用 nbstripout 过滤 ├── data/ # 符号链接到外部存储绝不放原始数据进 git │ └── raw/ # 指向 /mnt/nas/dataset/voc2012 的软链 ├── models/ # 训练产出.pt/.onnx/.h5设为 git-lfs 跟踪 ├── docs/ # Sphinx 生成的 API 文档源码 ├── scripts/ # 一键部署/数据预处理/环境校验脚本bash python 混合 ├── tests/ # pytest 用例覆盖核心函数输入输出边界 ├── .github/ # GitHub 专属配置Actions 工作流、ISSUE 模板 ├── pyproject.toml # 统一依赖管理替代 setup.py requirements.txt └── README.md # 用 Mermaid 画架构图 三步快速启动命令提示data/下所有子目录必须用ln -s指向外部路径Git 只跟踪软链接文件本身。这样既保证仓库轻量又避免同事 clone 后因缺数据而报错。2.2 分支策略不是教条基于交付节奏选 trunk-based development 或 git-flow 变体你不需要死守“master 是稳定版、develop 是集成版”这种老派规则。实际中我根据项目生命周期动态切换课程设计/4 周内交付原型用单分支main 标签tag管理里程碑。每次 commit 前跑pytest tests/ --tbshort失败则禁止 push。用git tag v0.1.0 -m 支持 VOC 格式加载标记可演示节点。毕业设计/3 个月迭代启用main生产就绪dev集成测试双分支。所有功能开发从dev拉新分支如feat/yolo-v8-export合并前必须通过 GitHub Actions 的 lint test build 三阶段检查。长期维护的工具库采用 trunk-based developmentTBD取消长期功能分支。所有修改直接向main提 PR但强制要求PR 标题含[WIP]或[READY]状态标识描述区粘贴pre-commit run --all-files输出关联至少一个 Issue如Closes #23。关键不是分支名而是每个分支背后绑定的自动化门禁。比如dev分支的推送会触发build-docker-image.yml而main分支的 merge 会触发publish-pypi.yml—— 这些才是真实约束力。2.3 .gitignore 必须手写不能靠在线生成器JavaScript 项目特有陷阱JavaScript 生态的临时文件比 Python 更隐蔽。以下是我从某跨平台系统实战中总结的.gitignore核心段落已剔除通用模板只留 JS 项目高频踩坑项# Node.js 构建产物比 node_modules 更危险的是这些 dist/ build/ out/ .next/ .nuxt/ # TypeScript 编译残留即使你用 tsc --noEmitwatch 模式仍会生成 *.js.map *.d.ts # 包管理器元数据yarn.lock/npm-shrinkwrap.json 二选一保留 yarn.lock # 但禁止提交 pnpm-lock.yaml错pnpm 用户必须提交它否则 workspace 依赖解析失败 pnpm-lock.yaml # VS Code 调试配置launch.json 含本地路径绝对不能进仓库 .vscode/launch.json # 浏览器 DevTools 保存的断点Chrome 会自动生成 *.breakpoints.json # Cypress E2E 测试的视频与截图体积大且含敏感路径 cypress/videos/ cypress/screenshots/ # 最关键不要忽略 .env但要忽略 .env.local本地密钥 .env !.env.example # 示例文件必须提交供新人复制修改注意.env行末的!.env.example是白名单语法表示“忽略所有.env*但.env.example除外”。很多团队因漏写这行导致新人 clone 后找不到环境变量模板硬编码密钥进代码——这是安全审计的高危项。3. GitHub Actions 自动化流水线用 YAML 写出可调试的 CI/CD而非黑匣子3.1 为什么 80% 的 Actions 失败源于 job 间环境隔离失效GitHub Actions 默认每个 job 运行在全新虚拟机上这意味着npm install在 build job 装的包test job 里根本不存在。新手常写# ❌ 错误示范假设依赖全局安装 jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: npm ci - run: npm run build test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: npm test # 此处 npm 未安装直接报 command not found正确做法是用actions/cachev4缓存node_modules并显式声明 cache key# ✅ 正确用 package-lock.json 内容哈希作为缓存键 jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Cache node_modules uses: actions/cachev4 with: path: node_modules key: ${{ runner.os }}-node-${{ hashFiles(**/package-lock.json) }} - name: Install dependencies run: npm ci - name: Build run: npm run build test: needs: build runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Cache node_modules uses: actions/cachev4 with: path: node_modules key: ${{ runner.os }}-node-${{ hashFiles(**/package-lock.json) }} - name: Install dependencies run: npm ci - name: Run tests run: npm test逻辑说明hashFiles(**/package-lock.json)会计算所有 lock 文件内容的 SHA256只要依赖没变缓存 key 就一致test job 就能复用 build job 的node_modules。参数path: node_modules指定缓存目录runner.os避免 macOS 与 Linux 缓存混用。3.2 JavaScript 单元测试必须带覆盖率上传用 nyc codecov 实现质量门禁仅跑npm test不够必须量化“测得全不全”。我用nycistanbul注入覆盖率收集再推送到 Codecov- name: Test with coverage run: npx nyc --reportertext --reporterlcov npm test - name: Upload coverage to Codecov uses: codecov/codecov-actionv3 with: token: ${{ secrets.CODECOV_TOKEN }} # 在仓库 Settings Secrets 中配置 file: ./coverage/lcov.info flags: unittests name: codecov-umbrella关键参数说明--reportertext在 Actions 日志中打印终端覆盖率报告如Statements : 85.2%--reporterlcov生成coverage/lcov.info供 Codecov 解析flags: unittests标记此上传属于单元测试维度便于后续按测试类型分层分析。注意nyc必须在package.json的scripts.test中前置例如test: nyc --silent mocha test/**/*.spec.js。若用 Jest直接jest --coverage即可无需 nyc。3.3 避坑JavaScript 项目 CI 常见问题排查清单现象原因解决npm ci报错Cannot find module typescriptpackage.json中devDependencies缺少typescript但tsconfig.json存在导致nyc启动时尝试加载 TS 编译器在devDependencies中显式添加typescript: ^5.0.0并确保tsc --version在 Actions 中可执行Cypress E2E 测试在 CI 中白屏GitHub Actions 默认浏览器无 GPU 加速且未设置--headlessnew参数在cypress.yml中添加env: CYPRESS_VIDEO: false和CYPRESS_BROWSER: chrome并在run步骤加--browser chrome --headless --no-sandbox --disable-gpunyc覆盖率报告始终为 0%源码使用 ES Module 语法import/export但nyc默认不处理.mjs文件在.nycrc中添加extension: [.js, .cjs, .mjs]并设置require: [esm]npm publish失败提示401 UnauthorizedNPM_TOKENsecret 未在仓库 Settings Secrets 中配置或 token 权限不足需勾选Automation进入 npmjs.com → Account → Tokens → Generate new token → Type 选Automation→ 复制后粘贴到 GitHub Secretskey 命名为NPM_TOKEN4. Issue 与 Pull Request 的工程化用法把需求、缺陷、评审变成可追踪的数据资产4.1 Issue 模板不是形式主义用 YAML 定义结构化字段驱动自动化分类GitHub 支持 YAML 格式的 Issue 模板这能让“新增功能”“修复 Bug”“文档改进”自动打标并路由到对应负责人。例如.github/ISSUE_TEMPLATE/feature_request.ymlname: 新增功能 about: 提出一个新特性需求 title: [Feature] labels: [enhancement, triage] assignees: [developer-a] # 自动分配给 A 同学初审 body: - type: input id: impact attributes: label: 影响范围影响几个模块 description: 例如仅影响 src/utils/logger.js或涉及 src/core/ 与 tests/ validations: required: true - type: dropdown id: priority attributes: label: 优先级 options: - P0阻塞发布 - P1本周内需排期 - P2下月迭代 - type: textarea id: use-case attributes: label: 典型使用场景请描述用户操作流程 description: 例如“用户上传图片 → 点击‘增强’按钮 → 页面显示处理后图像” placeholder: | 1. 用户在 Web 界面选择一张 JPEG 图片 2. 点击「超分」按钮 3. 前端调用 /api/super-res API 4. 返回 base64 图像并渲染效果当用户填写此模板提交 IssueGitHub 自动生成带impact、priority字段的 issue并自动打上enhancement标签。后续可用 GitHub Search 过滤label:enhancement priority:P0快速定位高优需求。4.2 PR 描述必须含可验证的验收标准拒绝“已修复”这类玄学表述PR 描述是代码变更的契约。我强制要求每份 PR 描述包含## 验收标准区块且每条标准必须可执行、可观测## 验收标准 - [x] npm run build 成功生成 dist/bundle.js文件大小 ≤ 120 KB原为 145 KB - [x] 在 Chrome 120、Firefox 115 中打开 http://localhost:3000/demo点击「导出 ONNX」按钮后控制台无 TypeError 报错 - [x] 运行 npm test -- --testPathPatternonnx-export.spec.js全部 5 个用例通过 - [ ] 待测在 NVIDIA T4 GPU 上运行 python scripts/test_onnx_inference.py --model dist/model.onnxFPS ≥ 23提示带[ ]的条目表示尚未验证合并前必须打钩。这种写法倒逼开发者在提 PR 前完成本地验证而不是把测试甩给 CI。4.3 利用 GitHub Projects 看板实现需求穿透从 Issue 到代码再到部署状态Projects 看板不是 To-do List而是状态机。我为某图像处理 Demo 配置了四列列名触发条件自动化动作BacklogIssue 创建且无triage标签GitHub Action 自动添加triage标签In ProgressIssue 被 assignee 接收或 PR 关联该 Issue当 PR 的 title 含Closes #123自动将 #123 移入此列Review ReadyPR 通过所有 CI 检查且有 ≥2 个 approve用pull-request-approval-action检测 approve 数达标后移动卡片DonePR 合并到main分支GitHub webhook 监听pull_request.closed事件自动归档关键技巧每张卡片右上角显示Status: deployed或Status: pending CI这是用 GitHub API 查询 Actions 运行状态后动态更新的。这样产品经理刷看板时一眼就能看出“用户登录优化”这个需求是否已上线。5. JavaScript 项目的安全加固从依赖扫描到 SCA绕过 npm audit 的认知陷阱5.1npm audit是过时方案用snyk test替代精准定位供应链风险npm audit仅检查package-lock.json中的直接依赖对 transitive dependency传递依赖漏报严重。例如lodash的prototype pollution漏洞可能藏在webpack - terser - acorn链路中npm audit无法告警。我改用 Snyk CLI# 安装并认证token 在 snyk.io 获取 npm install -g snyk snyk auth # 扫描项目生成 HTML 报告 snyk test --filepackage-lock.json --severity-thresholdhigh --json snyk-report.json snyk monitor # 上传到 Snyk 云平台持续跟踪新漏洞Snyk 的优势在于基于真实 exploit 数据库而非 CVE 静态匹配显示漏洞影响路径如acorn7.4.0 ← terser5.16.0 ← webpack5.88.0提供snyk wizard交互式升级建议自动修改package.json。注意--severity-thresholdhigh表示只报告 high/critical 级别漏洞避免低危告警淹没有效信息。5.2 防御恶意包投毒用lockfile-lint强制校验 package-lock.json 完整性2023 年多起 npm 包投毒事件源于攻击者篡改package-lock.json中的resolved字段指向恶意镜像。lockfile-lint可在校验阶段拦截npm install --save-dev lockfile-lint在.lockfile-lintrc.json中配置{ allowedHosts: [registry.npmjs.org, github.com], allowedSchemes: [https:, githttps:], enforceTopLevelDependency: true, allowedIntegrityAlgorithms: [sha512, sha384] }然后在 CI 中加入步骤- name: Validate lockfile run: npx lockfile-lint --type npm --path package-lock.json参数说明allowedHosts只允许从官方 registry 或 GitHub 拉取包enforceTopLevelDependency禁止package-lock.json中出现未在package.json声明的顶层依赖防postinstall脚本偷偷装包allowedIntegrityAlgorithms强制使用强哈希算法拒绝sha1已被破解。5.3 避坑JavaScript 依赖安全常见误区与真相误区真相行动建议“只要npm update就安全”npm update只升到package.json中^或~允许的最高版本可能跳过含漏洞的中间版本改用npm outdated查看可升级列表再手动npm install lodash4.17.21指定修复版本“私有 registry 就绝对安全”私有 registry 若未开启audit代理或缓存污染防护仍可能同步恶意包在私有 registry如 Verdaccio配置security插件启用snyk或ossindex实时扫描“TypeScript 能防止运行时漏洞”TS 仅做编译期类型检查对原型链污染、正则 DoS、HTTP header 注入等完全无效必须配合snyk testeslint-plugin-security检查eval()、new Function()等危险 API“忽略 devDependencies 的漏洞”devDependencies中的webpack-dev-server若含 XSS 漏洞本地开发时浏览器访问localhost:8080即被攻击在snyk test中移除--dev参数全量扫描所有依赖6. 从“能跑通”到“可交付”用 GitHub Release GitHub Pages 构建最小可行交付物6.1 Release 不是打标签用 GitHub Actions 自动生成 changelog 与二进制包Release 页面是用户第一眼看到的交付物。我拒绝手写v1.2.0更新日志而是用conventional-commits规范提交信息再由standard-version自动生成# 安装并初始化 npm install --save-dev standard-version npx standard-version --init约定提交前缀feat:新功能触发 minor 版本fix:修复 bug触发 patch 版本docs:文档变更不触发版本号chore:构建脚本修改不触发版本号然后在.github/workflows/release.yml中on: push: tags: - v[0-9].[0-9].[0-9] # 匹配 v1.2.0 格式 tag jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 # 必须获取全部 commit 历史 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 18 - name: Install dependencies run: npm ci - name: Generate changelog and publish run: npx standard-version --skip.commit --skip.tag env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}效果当执行git tag v1.2.0 git push origin v1.2.0Actions 自动解析feat:/fix:提交生成CHANGELOG.md打包dist/下的bundle.js与index.html为my-app-v1.2.0.zip创建 Release 页面附带下载链接与版本差异Compare v1.1.0...v1.2.0。6.2 GitHub Pages 不只是静态站用gh-pages发布可交互的 JavaScript DemoGitHub Pages 常被当作文档托管但它能直接运行前端应用。以一个 YOLOv8 Web Demo 为例# 安装 gh-pages npm install --save-dev gh-pages在package.json中添加脚本scripts: { deploy: gh-pages -d dist -b gh-pages -r https://github.com/username/my-vision-project.git }dist/目录结构需满足dist/ ├── index.html # 入口页含 script srcbundle.js/script ├── bundle.js # Webpack 打包产物含模型权重 base64 编码 ├── assets/ # 图片、字体等静态资源 └── manifest.json # PWA 配置可选关键配置在webpack.config.js中设置output.publicPath: /否则bundle.js加载路径会错。部署后访问https://username.github.io/my-vision-project/即可在线体验无需任何服务器。6.3 验证交付物完整性的终极 checklist我每次发布前必跑的 5 项验证少一项都不点 Merge验证项命令/操作通过标准1. 构建产物完整性unzip -l my-app-v1.2.0.zip | grep -E \.(js|html|css)$列出所有 JS/HTML/CSS 文件确认无缺失2. 浏览器兼容性在 BrowserStack 中打开https://username.github.io/my-vision-project/测试 Chrome/Firefox/Safari 最新版页面渲染正常控制台无Uncaught SyntaxError3. 离线可用性断网后刷新页面检查 Service Worker 是否激活Application → Service Workers显示Status: activated且index.html可离线加载4. 安全头信息curl -I https://username.github.io/my-vision-project/响应头含Content-Security-Policy: default-src self5. Lighthouse 性能分Chrome DevTools → Lighthouse → Mobile → Generate reportPerformance ≥ 85Accessibility ≥ 90SEO ≥ 95从那以后我每次发布 Release都强制走一遍这个 checklist —— 不是因为信不过 CI而是因为真实用户用的不是 Ubuntu runner而是带着各种插件、旧版浏览器、弱网环境的 Chrome。希望帮到你。本文还有配套的精品资源点击获取
