jQuery:用统一 API 构建浏览器与 Node JavaScript 应用
一个给 JavaScript 项目统一操作 DOM 的库,也支持 Node 和 ESM,4.x 仍在完整维护。
GitHub jquery/jquery 更新 2026-11-19 分支 main 星标 60.0K 分叉 20.7K
JavaScript DOM 操作 QUnit Node.js ECMAScript Modules 浏览器

🧭 决策指南

适合,如果你

  • 你维护浏览器 JavaScript 应用,并需要 jQuery 的 DOM、事件或构建能力。
    README 的“Environments in which to use jQuery”与“ How to build your own jQuery”章节。
  • 你的项目需要 Node、浏览器扩展或其他非浏览器环境中的 jQuery。
    README 明确写有“jQuery also supports Node, browser extensions, and other non-browser environments.”
  • 你需要生成 jquery.slim.js、jquery.module.js 或自定义模块构建。
    README 的“Build all jQuery release files”与“Building a Custom jQuery”章节。

不适合,如果你

  • 你的部署仍依赖 jQuery 1.x 或 2.x 的官方维护。
    README 的“Version support”表格标明 1.x、2.x 为 None。
  • 你要求所有自定义构建都经过项目持续测试。
    README 明确写有“Non-official custom builds are not regularly tested. Use them at your own risk.”
  • 你的测试环境无法提供支持 PHP 的本地服务器。
    README 的“Running the Unit Tests”章节要求使用支持 PHP 的本地服务器。

前置条件

  • 构建需要最新 Node.js/npm 和 git 1.7 或更高版本。
  • 单元测试需要支持 PHP 的本地服务器,并且必须从根目录运行站点。
  • README 写明“No database is required.”

第一步命令(README 原文)

npm run build

要注意

  • 排除 css 会连带移除 effects、offset 与 dimensions 模块。
    README 的“Custom Build Examples”说明。
  • 测试站点必须从根目录运行,不能从 test 目录运行。
    README 的“Running the Unit Tests”章节。
  • 执行 git reset --hard upstream/main 与 git clean -fdx 会删除本地工作内容。
    README 的“Cleaning”章节明确提醒工作内容会被清除。

替代方案

  • 原生 querySelectorAll:只需要选择器能力、不需要 jQuery 其他模块时,可使用 README 所述的原生 querySelectorAll 包装方式。
    Building a Custom jQuery

材料未说明

  • README 未提供 jQuery 4.1.0 的浏览器兼容性细节。
  • README 未给出 jQuery 4.1.0 相比 4.0.0 的具体变更列表。
  • README 未提供 npm 依赖数量、构建耗时或产物体积。
  • README 未说明 Node.js 的具体最低版本号,只写“latest Node.js/npm”。
  • README 未说明 60,008 星标与 2026-11-19 当日新增 266 星标的具体关注原因。

💡 深度解析

6
适合 我为传统管理后台制作定制 jQuery 构建,只需要 DOM、选择器和事件,明确不需要 Ajax、effects、offset、dimensions 和 wrap;能否直接排除这些模块?
适合读者: 为传统管理后台制作定制 jQuery 构建、只需要 DOM、选择器和事件而不需要 Ajax、动画或尺寸模块的前端工程师

适合,README 明确支持按模块排除,并且你列出的模块都有对应的排除方式;但必须保留 core,并注意模块依赖关系。

  • README 规定除 core 外任何模块都可以排除,因此 core 不能删除。
  • --exclude=ajax 可移除全部 Ajax 功能;排除 css 会连带移除 effects、offset、dimensions。
  • README 给出的组合示例还包含 -e wrap,说明这些顶层模块可以一起裁剪。
  • 非官方定制构建不会定期测试,README 明确要求使用者自行承担风险。

因此可以生成该构建,但它不是官方完整发行物,不能把“构建成功”当成所有后台功能仍然可用。

  • Building a Custom jQuery:Any module may be excluded except for core
  • Custom Build Examples:Exclude all ajax functionality: npm run build -- --exclude=ajax
  • Custom Build Examples:Excluding css removes effects, offset, dimensions
  • Custom Build Examples:Non-official custom builds are not regularly tested. Use them at your own risk
材料未说明:后台现有代码是否通过插件或间接调用了被排除模块;选择器、事件及其他保留模块之间是否存在该应用未覆盖的依赖关系
不适合 我准备参与 jQuery 核心开发,环境中可以安装最新 Node.js/npm 和 Git,但本机没有 PHP 服务器;我能否完成 README 所述的完整测试流程?
适合读者: 参与 jQuery 核心开发、使用 Node.js/npm 构建 JavaScript 库并需要运行 QUnit 测试的开源维护者

不适合直接完成完整测试流程,因为 README 明确要求通过支持 PHP 的本地服务器运行单元测试;Node.js/npm 和 Git 只能满足构建及部分开发准备。

  • README 的构建要求是 latest Node.js/npm 与 Git 1.7 或更高版本。
  • 运行测试章节要求使用支持 PHP 的本地服务器,并且必须从仓库根目录提供测试站点,且不需要数据库。
  • README 列出 Windows 的 WAMP、macOS 的 MAMP,以及 Linux 的 LAMP 方案,也列出 Mongoose 作为多平台选项。
  • 测试体系包含 QUnit,部分测试还可借助 iframe 测试辅助方法运行。

因此缺少 PHP 服务器会阻塞 README 定义的完整测试路径,而不是阻塞所有源码构建操作。

  • What you need to build your own jQuery:latest Node.js/npm and git 1.7 or later
  • Running the Unit Tests:Run the unit tests with a local server that supports PHP
  • Running the Unit Tests:Ensure that you run the site from the root directory, not the test directory
  • Running the Unit Tests:No database is required;列出 WAMP、MAMP、LAMP 和 Mongoose
npm install
材料未说明:当前操作系统及是否能够安装 WAMP、MAMP、LAMP 或 Mongoose;README 未说明仅运行构建或部分 QUnit 测试时是否可以完全绕过 PHP 服务器
适合 我在浏览器扩展中使用 jQuery 4.x,要求通过 ESM 加载,并且扩展只做 DOM、事件和 CSS 操作;我能否基于 Slim 版本交付?
适合读者: 需要在浏览器扩展中以 ESM 方式加载 jQuery、同时希望移除 Ajax 和效果模块以控制资源体积的 JavaScript 开发者

适合,README 同时列出浏览器扩展支持、ESM 输出和 Slim 构建,这正好覆盖你的加载方式与功能裁剪需求。

  • README 说明 jQuery 支持 browser extensions,也支持其他非浏览器环境。
  • jquery.slim.module.js 是官方 Slim ESM 变体,输出到 dist-module/,并导出 jQuery 与 $ 命名导出。
  • Slim 构建可以排除 Ajax;README 还说明排除 CSS 会连带移除 effects、offset 和 dimensions,因此若仍需要 CSS 操作,不能简单采用排除 CSS 的方案。

你的需求与官方变体匹配,但仍需确认扩展是否依赖被 Slim 移除的 Ajax 或效果功能。

  • Environments in which to use jQuery:jQuery also supports Node, browser extensions, and other non-browser environments
  • Build all jQuery release files:jquery.slim.module.js 是 ESM 变体并放置于 dist-module/
  • Custom Build Examples:Excluding css removes modules depending on CSS: effects, offset, dimensions
npm run build -- --filename=jquery.slim.module.js --slim --esm
材料未说明:浏览器扩展的打包器是否正确处理该 ESM 文件及命名导出;扩展代码是否间接使用了 Slim 中不存在的 Ajax、effects、offset 或 dimensions
视情况 我维护一个仍使用 jQuery 1.x 或 2.x 的传统多页面网站,现有插件和旧接口较多;现在升级到 jQuery 4.x 是否合适?
适合读者: 维护仍运行 jQuery 1.x 或 2.x 的传统多页面网站、依赖既有插件且计划升级到当前受支持版本的前端开发者

视情况,但长期继续停留在 1.x 或 2.x 并不合适,因为这两个分支已经停止支持,4.x 才是当前完整支持的版本。

  • README 的版本支持表明确写出:4.x 为 Full,3.x 仅 Critical-only,2.x 和 1.x 为 None。
  • README 建议所有用户升级到最新版本,以获得更好的性能、安全性和功能。
  • 如果插件依赖已移除或变更的接口,升级成本取决于插件兼容性;README 没有提供具体插件兼容矩阵或自动迁移路径。

因此,项目方向上适合升级,但不能仅凭主版本号判断现有站点能否直接替换。

  • Version support:4.x Full;3.x Critical-only;2.x and 1.x None
  • Version support 原句:We recommend that all users upgrade to the latest version of jQuery
  • 项目洞察:升级时历史插件、旧浏览器兼容策略和弃用 API 可能成为迁移成本
材料未说明:现有插件是否兼容 jQuery 4.x;站点实际使用了哪些已移除或弃用的 API;目标浏览器范围及其与 jQuery 4.x 的兼容性
适合 我维护一个传统多页面网站,需要统一处理 DOM 选择、事件、Ajax、CSS 和基础动画,但不需要组件模型、路由或响应式状态管理;jQuery 4.x 是否适合继续使用?
适合读者: 维护传统多页面网站、只需要 DOM 选择器、事件、Ajax 和基础动画的 JavaScript 开发者,不计划引入完整单页应用框架

适合,jQuery 4.x 的能力边界正好覆盖传统多页面网站的 DOM、事件、Ajax、CSS 和基础动画需求,而不是要求你重构成单页应用。

  • 项目洞察明确列出选择器与遍历、事件、Ajax、CSS、effects、offset、dimensions 和 wrap 等模块。
  • README 的当前支持表显示 4.x 为 Full,适合作为新的受支持版本。
  • 项目洞察指出,jQuery 更现实的价值在存量系统维护、插件兼容和低成本渐进式改造。
  • 但它不提供组件模型、响应式状态管理、路由或完整 SPA 工程架构;如果需求后来转为复杂组件化应用,单独依赖 jQuery 就不匹配。

按你描述的约束,使用它是能力匹配,而不是把它当现代应用框架。

  • 项目洞察 solution_analysis:selector、ajax、css、effects、offset、dimensions、wrap 模块
  • Version support:4.x Full
  • 项目洞察 market_gap:现实价值更多体现在存量系统维护、插件兼容和低成本渐进式改造
  • 项目洞察 usage_limitations:不提供组件模型、响应式状态管理、路由或完整工程架构
材料未说明:网站当前依赖的插件是否支持 jQuery 4.x;实际页面是否使用了已废弃或移除的接口;目标浏览器范围及其对 jQuery 4.x 的支持情况
不适合 我需要在 Node 和浏览器扩展两个环境中复用部分 jQuery 能力;README 明确支持这两个环境,但它是否意味着所有 DOM、Ajax 和事件功能都能无差别运行?
适合读者: 需要在 Node 环境和浏览器扩展之间复用 jQuery 能力、但不准备采用完整浏览器页面运行模型的 JavaScript 开发者

不适合把“支持 Node 和浏览器扩展”理解成所有浏览器功能都能无差别运行;README 只确认环境支持范围,没有承诺完整 DOM、网络和事件能力在各环境一致。

  • README 写明 jQuery 支持 Node、browser extensions 及其他非浏览器环境,但没有逐项说明 DOM、Ajax 或事件模块的运行边界。
  • 项目洞察指出,jQuery 依赖目标环境提供相应 DOM、网络和事件能力,不能消除所有环境差异。
  • jQuery 的主要定位仍是浏览器 DOM 增强和交互层,因此 Node 中能复用的范围取决于运行时是否提供所需对象。

可以复用,但应按具体模块和运行时能力判断,不能仅凭环境列表作全面兼容结论。

  • Environments in which to use jQuery:jQuery also supports Node, browser extensions, and other non-browser environments
  • 项目洞察:项目依赖浏览器或目标运行环境提供相应 DOM、网络和事件能力
  • 项目洞察:jQuery 主要解决 DOM 增强和浏览器交互问题
材料未说明:Node 运行时是否提供项目所需的 document、window 或其他 DOM API;浏览器扩展使用的是页面上下文、内容脚本还是后台环境;目标功能是否依赖 Ajax、事件或 CSS 等浏览器特有能力

✨ 核心亮点

  • 支持浏览器、Node 与浏览器扩展环境
  • npm run build 可生成 dist 构建产物
  • 支持 jquery.slim.js 与 ESM 构建
  • 4.x 完整支持,3.x 仅接收关键更新

🔧 工程化

  • 用 npm run build 构建 jQuery,并输出 dist/ 与压缩文件
  • npm run build:all 可生成 jquery.js、slim 与 module 变体
  • Build Script 支持排除 ajax、css、deprecated 等模块
  • QUnit 测试套件提供 DOM、iframe 与原生事件测试方法

⚠️ 风险

  • 2.x 与 1.x 已停止支持,3.x 仅提供关键更新
  • 自定义构建未被定期测试,README 明确提示自行承担风险
  • 运行单元测试需要支持 PHP 的本地服务器
  • 构建要求最新 Node.js/npm 与 git 1.7 或更高版本

👥 适合谁?

  • 维护浏览器 JavaScript 应用且需要 DOM API 的团队
  • 需要 Node、浏览器扩展或其他非浏览器环境支持的开发者
  • 需要 jquery.slim.js 或 ECMAScript Modules 产物的项目