axios 贡献实战指南代码风格、Conventional Commits、Vitest 测试体系与构建沙箱验证全流程【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios本文以 axios 仓库的 CONTRIBUTING.md 为骨架逐条展开其中的贡献规则代码风格、提交信息规范、测试要求、文档同步策略与依赖更新边界并结合 package.json、vitest.config.js、.github/dependabot.yml 与 CI 工作流等仓库证据把每一条规则落到可复制、可验证的本地操作上。读完本文你将能够独立完成一次合格的 axios 贡献从npm ci安装、本地跑通单元测试与浏览器测试到用 examples/sandbox 做手工验证再到按 commitlint 规范提交并理解 GitHub Actions 如何审查你的 PR。一、贡献前置行为准则与代码风格CONTRIBUTING.md 开篇即声明向 axios 提交贡献即表示同意遵守 CODE_OF_CONDUCT.md 行为准则。这是所有贡献流程的第一道边界。1.1 代码风格Node 风格指南 仓库 ESLint 落地原文档要求遵循 Node 风格指南node style guide。落到本仓库代码风格有两层机器化约束ESLint 检查。package.json 中的脚本定义了检查入口lint: eslint lib/**/*.js, fix: eslint --fix lib/**/*.js即 lint 只针对lib/下的运行时源码配置见 eslint.config.js。CI 流水线.github/workflows/run-ci.yml在构建前会先执行npm run lint风格不达标直接失败。Prettier 格式化钩子。package.json 中的lint-staged配置会在暂存文件上自动运行prettier --writelint-staged: { *.{js,cjs,mjs,ts,json,md,yml,yaml}: prettier --write }配合 package.json 中prepare: husky安装的 git hooks格式化在提交流程中自动完成。1.2 从源码结构可以看到的风格惯例仓库内 AGENTS.md贡献者/AI Agent 的规范指南对lib/源码风格做了成文约定与 CONTRIBUTING.md 的Follow the node style guide互为补充从源码结构看这些惯例已稳定存在类用 PascalCaseAxios、AxiosError、InterceptorManager函数用 camelCasebuildURL、mergeConfig、dispatchRequest错误码是AxiosError上的 UPPER_SNAKE_CASE 常量ERR_NETWORK、ETIMEDOUT等列表在 lib/core/AxiosError.js新lib/**/*.js文件使用 ESM import 并带显式.js扩展名axios 自身产生的失败一律抛AxiosError而非裸Error第三方错误用AxiosError.from(error, code, config, request, response)包装内部类槽位用Symbol键如lib/core/AxiosHeaders.js中的Symbol(internals)而不是下划线属性。这些惯例在 lib/ 目录下随处可见写新代码前对照同目录文件是最快的风格对齐方式。二、Commit MessagesConventional Commits 与 commitlint 强制链CONTRIBUTING.md 要求提交信息遵循 Conventional Commits 规范feat:、fix:、chore:、docs:等前缀。这不是软性建议仓库里有一条完整的强制链本地钩子.husky/commit-msg 在git commit时执行npx commitlint --edit $1不符合规范的提交信息会被直接拒绝规范配置package.json 中内嵌了 commitlint 配置继承commitlint/config-conventional并额外放宽了头部长度commitlint: { rules: { header-max-length: [2, always, 130] }, extends: [commitlint/config-conventional] }即提交头最长 130 字符默认是 100这为带 scope 的较长提交信息留了空间发布工具依赖COLLABORATOR_GUIDE.md 明确指出 PR 标题同样使用 Conventional Commits因为发布工具链依赖这个格式来推导变更类型。从源码结构看commitlint、husky、lint-staged均声明在 package.json 的devDependencies中commitlint/cli、commitlint/config-conventional、husky、lint-staged三者构成安装即启用的本地质量门禁。三、Testing测试要求、Vitest 测试体系与 CI 门禁CONTRIBUTING.md 的 Testing 一节只有两条硬性要求Update tests for your changes. Pull requests must pass GitHub Actions.为你的改动更新测试PR 必须通过 GitHub Actions。下面把这两条要求拆解为可操作的具体内容。3.1 一个需要注意的文档差异CONTRIBUTING.md 的 Developing 一节写的是npm run testruns the Jasmine and Mocha tests但当前仓库中该脚本实际为test: npm run test:vitest, test:vitest: vitest run见 package.json。也就是说测试框架已从 Jasmine/Mocha 迁移到Vitestvitest在 devDependencies 中tests/下的用例均为 Vitest 风格。以当前 package.json 与 vitest.config.js 为准npm run test现在运行的是 Vitest 套件原文档此处属于历史遗留描述。3.2 三个测试 projectunit / browser / browser-headlessvitest.config.js 定义了三个测试 project这也是理解更新测试该更新哪里的关键projects: [ { name: unit, environment: node, include: [tests/unit/**/*.test.js] }, { name: browser, include: [tests/browser/**/*.browser.test.js], browser: { enabled: true, provider: playwright(), instances: [{ browser: chromium }] }, setupFiles: [tests/setup/browser.setup.js] }, { name: browser-headless, /* chromium firefox webkit 三浏览器 headless */ } ]对应可运行的命令均来自 package.json命令作用npm run test:vitest全量运行等价于npm run testnpm run test:vitest:unit只跑 Node 端单元测试tests/unit/**npm run test:vitest:browser跑真实浏览器Playwright chromiumnpm run test:vitest:browser:headless三浏览器无头模式与 CI 完全一致npm run test:vitest:watchwatch 模式开发其中 vitest.config.js 还统一设置了testTimeout: 10000。浏览器测试需要先安装 Playwright本地npx playwright installCI 用npx playwright install --with-deps见 AGENTS.md。3.3 tests/ 目录的分工与编写规范仓库内有一份专门针对测试目录的细则 tests/README.md它是Update tests for your changes的落地标准目录布局runtime-firsttests/unitNode 端聚焦测试、tests/browser浏览器运行时行为、tests/smoke打包兼容冒烟套件、tests/setup共享工具文件命名单元测试*.test.js浏览器测试*.browser.test.jsESM 冒烟*.smoke.test.jsCJS 冒烟*.smoke.test.cjs单元测试要求adapter/网络类测试优先使用 tests/setup/server.js 提供的本地测试服务器startHTTPServer、stopHTTPServer、stopAllTrackedHTTPServers并用try/finally保证清理避免泄漏的服务器导致 Vitest 挂起fixtures 就近放置如 tests/unit/adapters/ 下的cert.pem、key.pem浏览器测试要求用文件内MockXMLHttpRequest风格 mock在beforeEach替换全局 XHR、afterEach还原断言聚焦可观测的请求/响应行为冒烟测试要求ESM 与 CJS 两套覆盖保持对齐——在一个格式里新增场景时另一个格式也要加等价用例对应 tests/smoke/esm/tests/ 与 tests/smoke/cjs/tests/收尾清单文件放对目录、命名匹配、setup/teardown 不留全局状态、断言确定性优先、避免无谓的时序/网络抖动。此外还有两套针对打包产物而非源码树的兼容测试tests/smoke/cjs、esm、deno、bun 四套对应 package.json 的test:smoke:*脚本与tests/module/cjs 用 TypeScript 4.9、esm 用 TypeScript 5.x 验证类型声明见 AGENTS.md。运行它们需要先npm run build、npm pack再把 tarball 安装进对应目录执行。3.4 CI 如何校验你的 PRCONTRIBUTING.md 要求PR 必须通过 GitHub Actions。主 CI 定义在 .github/workflows/run-ci.yml其build-and-run-vitestjob 的顺序是npm ci --ignore-scripts → npm run lint → npm run build → npx playwright install --with-deps → npm run test:vitest:unit → npm run test:vitest:browser:headless → npm pack → Dependency Review → 上传 axios-*.tgz 工件随后cjs-smoke-tests等 job 在 Node 12/14/16/18 矩阵上消费打包工件。AGENTS.md 概括的完整 CI 顺序为install → build → Playwright 安装 → unit → browser headless → pack → CJS/ESM module 与 smoke 测试 → Bun/Deno smoke 测试。另外注意 package.json 的prepare: husky在 CI 里被.npmrc的ignore-scriptstrue跳过所以 CI 安装统一使用npm ci --ignore-scripts——本地贡献时同样建议用npm ci。四、DocumentationAPI 变更必须同步文档CONTRIBUTING.md 规定API 发生变化时必须更新文档让 API 与文档保持同步。仓库中文档的实体是 docs/ 目录按语言分四份镜像英文 docs/pages/ 与docs/es/、docs/fr/、docs/zh/覆盖 getting-started、advancedadapters、interceptors、error-handling 等 26 篇与 misc 三大块。在操作层面还有两条来自 AGENTS.md 的成文流程约束值得贡献者特别注意未发布变更的写法用户可见但未发布的变化写入 PRE_RELEASE_CHANGELOG.md而不是 CHANGELOG.md后者只在正式发布时更新文档待办登记README、文档站、examples、迁移指南与翻译文档的更新先在 PRE_RELEASE_DOCS.md 登记留足上下文供发布阶段落实避免存储脆弱的行号级 diff。另外公共 API 变更时要同时更新两套类型声明index.d.tsESM与 index.d.ctsCJS 的export axios形态。这一点也写进了 PULL_REQUEST_TEMPLATE.md 的提交前 ChecklistDocs/types updated if public API changed可作为自核对表使用。五、Dependency 与 GitHub Actions 更新仅限维护者/BotCONTRIBUTING.md 用一整节划定了边界不要仅更新 npm 包、lockfile 或 GitHub Actions 版本就开 PR外部协作者的此类 PR 会被直接关闭只有维护者和获批的自动 bot 可以创建这类 PR且保留 7 天 Dependabot 冷却期除非关键漏洞需要维护者手动介入。这条规则在仓库里有完整的机制佐证。.github/dependabot.yml 配置了github-actions生态周更、cooldown.default-days: 7所有 Actions 归入github-actions分组npm生态周更、open-pull-requests-limit: 5、7 天冷却minor/patch 按 production 与 development 分两组且ignore了所有semver-major版本更新——大版本升级不走自动 PR自动 PR 统一打commit::choretype::automated-pr标签与 commitlint 的 conventional 分类衔接。配套的 lockfile 安全审查在 .github/workflows/lockfile-lint.yml由 AGENTS.md 说明package-lock.json会被检查 npm HTTPS host 与 integrity hash。因此如果你确需修改依赖COLLABORATOR_GUIDE.md 给出的红线是不新增运行时依赖依赖面被刻意压到最小当前 runtime 依赖仅 4 个follow-redirects、form-data、https-proxy-agent、proxy-from-env见 package.jsonlockfile 变更必须让 lockfile-lint 通过。六、本地开发命令详解test / build / versionCONTRIBUTING.md 的 Developing 一节列了三个命令逐一对照 package.json 的实际实现build: gulp clear cross-env NODE_ENVproduction rollup -c, version: npm run build git add package.json, preversion: gulp versionnpm run test即vitest run第 3.1 节已说明从 Jasmine/Mocha 迁移到 Vitest 的事实。开发中更常用的是npm run test:vitest:unit只跑 Node 单测速度快与npm run test:vitest:watchnpm run build先由gulp clear清理 dist/再以NODE_ENVproduction跑 Rollup产出浏览器 ESM/UMD/CJS 与 Node CJS 各形态包。注意dist/是生成物不要手工编辑package.json的files字段与exports映射package.json定义了各运行时browser / react-native / bun / node分别取哪个产物npm run versionpreversion钩子先执行gulp version生成版本相关文件如lib/env/data.js再构建并把package.json加入暂存是发布准备流程的一部分——普通功能开发不要触碰版本生成文件见 AGENTS.md。本地还有一条容易被忽略的安装约束.npmrc 设置了ignore-scriptstrue。若npm ci后需要 git hooks需手动执行一次npm rebuild husky npx huskyAGENTS.md。七、手动验证examples 与 sandboxCONTRIBUTING.md 的最后一节教你用示例做手工测试仓库中对应两个独立的服务端。7.1npm run examples示例矩阵服务脚本examples: node ./examples/server.js对应 examples/server.js。它的行为从源码可以完整读出启动一个纯 Nodehttp服务默认端口argv.p || 3000examples/server.js所以文档说Open 127.0.0.1:3000根路径返回一个自动生成导航页把examples/下每个子目录abort-controller、amd、get、post、postMultipartFormData、transform-response、upload等渲染成链接请求/get这类目录会被重写为/get/index.html形如dir/server的 URL 会动态 import 对应的dir/server.js并交给它处理请求examples/server.js——这正是示例页面能触发回显接口如 examples/get/server.js的机制静态资源方面axios.min.js等请求会直接回传../dist/下的构建产物因此跑 examples 前需要先npm run build生成 dist示例目录的使用说明见 examples/README.md。7.2npm start浏览器沙箱脚本start: node ./sandbox/server.js对应 sandbox/server.js它固定监听 3000 端口sandbox/server.js提供/→ sandbox/client.html浏览器调试页脚本为 sandbox/client.js/axios.js→../dist/axios.js同样是构建产物需先npm run build/api→ 一个通用回显接口收集请求体并尝试JSON.parse返回包含url、data、method、headers的 JSON 结果sandbox/server.js解析失败则返回 400端口被占用时会打印EADDRINUSE提示并关闭服务器sandbox/server.js避免静默失败。文档给出的浏览器沙箱用法npm start # 打开 127.0.0.1:3000用页面里的表单/输入区调试请求7.3node ./sandbox/client终端沙箱CONTRIBUTING.md 还给出终端用法npm start node ./sandbox/client即先起 sandbox/server.js 提供/api回显接口再用 sandbox/client.js 作为 Node 端客户端在终端里发起请求适合快速验证 Node 运行时行为而不必打开浏览器。八、贡献者自检清单汇总把全文各节的规则压缩成一张 PR 前核对表与 PULL_REQUEST_TEMPLATE.md 的 Checklist 相互印证安装npm ciCI 为npm ci --ignore-scripts受.npmrc约束风格npm run linteslint lib/**/*.js通过暂存文件已被 Prettier 处理提交信息Conventional Commits 前缀头部 ≤ 130 字符本地commit-msg钩子commitlint放行测试改动有对应单测涉及浏览器行为则更新tests/browser/**涉及打包/导入形态则同步更新tests/smoke/的 ESM 与 CJS 两侧浏览器用例用 tests/setup/ 共享工具并保证清理本地通过npm run test:vitest:unit与npm run test:vitest:browser:headlessCI 同参均为绿文档公共 API 变更时同步 docs/ 与 index.d.ts/index.d.cts未发布变更记入 PRE_RELEASE_CHANGELOG.md 与 PRE_RELEASE_DOCS.md依赖不单独提依赖/lockfile/Actions 升级 PR确需改动时保证 lockfile-lint 通过并先与社区讨论手工验证npm run build后跑npm run examples127.0.0.1:3000或npm start 浏览器/终端沙箱复现改动行为。以上规则与命令均以当前仓库axios 1.19.0的实际文件为准其中 CONTRIBUTING.md 里Jasmine and Mocha的表述与当前 Vitest 工具链存在出入贡献时以 package.json 与 vitest.config.js 的实际脚本为准。【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考