FingerprintJS 如何按贡献规范新增一个熵源并提交 PR【免费下载链接】fingerprintjsThe most advanced free and open-source browser fingerprinting library项目地址: https://gitcode.com/GitHub_Trending/fi/fingerprintjs你的任务是给 FingerprintJS 新增一个熵源entropy source并让 PR 符合项目贡献规范、能通过 CI 检查。完成后的结果新熵源出现在src/sources/index.ts的sources对象中有同目录的单元测试覆盖yarn lint、yarn build、yarn test:local全部通过。整个流程的依据是 contributing.md 中的Creating a pull request和How to add an entropy source两节本文所有命令均来自该文档与 package.json 的 scripts 定义。提交前先确认准入条件项目只接受对应标记为help wanted绿色徽章issue 的 PR。如果你发现的是新问题、想新增的熵源还没有对应 issue需要先提交 issue 并与维护团队讨论未经事先 review 的 issue 对应的 PR 不会因团队人力有限而被接受。PR 会被审查的硬性规则来自 contributing.md代码质量不低于被修改的代码风格语法、命名、编码模式遵循 FingerprintJS 现有风格所有新增代码必须有自动化测试覆盖contributing.mdWorking with code一节描述的所有检查必须通过变更必须向后兼容保证现有用户不改代码也能继续用非必要不加依赖如 Node 包不做与 PR 声明目的无关的修改改动尽量小不修改项目的代码风格、TypeScript 配置等主观性内容不接受 playground 目录的 PR该项目明确说明不处理 playground 的 PR。如果要做的事情比修一个小 bug 更复杂或不确定是否满足要求文档建议先发起 discussion。准备本地开发环境前置条件已安装 Git、Node.js 和 Yarn。然后克隆仓库并安装依赖git clone https://github.com/fingerprintjs/fingerprintjs.git cd fingerprintjs yarn install改完代码后可以用 playground 在本地跑起来观察效果可选文档提供了该工具yarn playground:start # Add --port 8765 to change the server port启动后在浏览器打开 http://localhost:8080FingerprintJS 会立即执行并把结果打印在页面上每次修改源码页面自动刷新。playground 自身的代码在 playground 目录。熵源必须满足的五条要求新增的熵源是一个获取浏览器某项数据、返回值参与生成 visitor identifier 的函数必须同时满足稳定在同一浏览器中包括 incognito、guest、桌面模式总是或几乎总是产生相同的值有区分度在不同浏览器、操作系统或设备上产生不同的值无副作用不产生控制台消息、DOM 变化、模态窗口、通知、声音等快速单个熵源完成时间不超过 1 秒不能只表示浏览器版本例如通过探测 JavaScript 特性得到的信号不算好熵源——自动更新会导致返回值变化区分度低且 User-Agent 字符串即可得到同样的熵。返回的熵组件entropy component必须是能编码进 JSON 的简单 JavaScript 值。实现两阶段函数load 与 get熵源运行分两个阶段load阶段在 agent 的load函数被调用时执行一次应把尽可能多的工作放在这里让 get 阶段尽量快可以启动会一直运行到 get 阶段的后台进程get阶段在每次调用 agent 的get函数时执行必须尽可能快。两阶段都可以是同步的如果组件在 load 完成后不会再变get 阶段可以省略contributing.md 中的文档示例async function entropySource() { const finalData await doLongAction() // If the sources returned value is not a function, its considered an entropy component return finalData // Equivalent to: return () finalData }如果需要 get 阶段则 load 阶段返回一个函数// The function below represents the load phase async function entropySource() { // The load phase starts here const preData await doLongAction() // The load phase ends when the entropySource function returns // The function below represents the get phase return async () { // The get phase starts here const finalData await finalizeData(preData) return finalData // The get phase ends then this returned function returns } }注意 load 阶段不应在源函数返回后仍在后台运行否则 agent 无法正确测得其执行时长同时 load 阶段只包含必要的动作以免阻塞整个 agent。错误处理上熵源只处理预期内的错误并把预期错误转换成特殊的熵组件值未预期的错误要重新抛出否则你无法知道熵源内部出了什么问题。contributing.md 给出的文档示例注意文档原文中第一个判断写的是而非实现时应自行修正async function entropySource() { try { // await is necessary to catch asynchronous errors return await doLongAction() } catch (error) { // WRONG: return error // Correct: if (error.message Foo bar) { return bot } if (/boo/.test(error.message)) { return ie } throw error // Unexpected error } }注册到 src/sources/index.ts熵源写完后把它加进 src/sources/index.ts。现有文件的结构是顶部逐个import各熵源再在sources对象中按名注册例如import getTouchSupport from ./touch_support // ... export const const sources { // ... touchSupport: getTouchSupport, // ... }该文件里的注释说明了顺序约定异步源放在前面以便与其他源并行运行有些源会影响其他源例如 WebGL 会影响 canvas这类源webGlBasics、webGlExtensions必须放在最后。新源插入时保持这一约定。文件头部还有一段 READ FIRST 注释指向 contributing.md 的熵源章节。写实现时还要遵守 contributing.mdPitfalls一节列出的坑避免在模块顶层执行表达式函数调用、属性访问、计算属性名等否则影响 tree-shaking避免直接使用navigator.userAgent这类易被篡改的 API需要按浏览器名和版本做判断时用 src/utils/browser.ts 中已有的函数测试代码中则反过来用 tests/utils/index.ts 的函数访问navigator.userAgent因为测试环境不会被篡改tsconfig.json的include参数只允许包含入口文件和.d.ts文件熵源中一些interface会被替换成type以避免使用 FingerprintJS 的项目出现 cannot be named 错误。编写单元测试每个熵源都要有单元测试测试文件与源文件放在同一目录例如 src/sources/touch_support.test.ts 对应 src/sources/touch_support.ts。测试用 Jasmine 语法在真实浏览器中通过 Karma 运行。测试的目的是验证熵源在所有受支持浏览器中返回预期值——当底层 API 发生显著变化或废弃时这些测试应该在未来浏览器版本上开始失败如必要还应加一个稳定性测试。contributing.md 建议参考 src/sources/ 下的现有测试。一个典型写法来自 src/sources/cookies_enabled.test.tsimport getCookiesEnabled from ./cookies_enabled describe(Sources, () { describe(cookiesEnabled, () { it(returns boolean, () { expect(getCookiesEnabled()).toBeInstanceOf(Boolean) }) }) })需要按设备类型断言时用 tests/utils/index.ts 的isMobile()、isTablet()等函数需要模拟属性或matchMedia时可以用withMockProperties、withMockMatchMedia见 src/sources/touch_support.test.ts 中对navigator.maxTouchPoints的 mock 用法。本地验证lint、build、测试按 contributing.md 的顺序执行以下命令与 package.json 中的 scripts 一一对应# 检查代码风格ESLint Prettier。CI 也会跑本地不强制lint:fix 可自动修复部分问题 yarn lint # 构建 dist 产物保存到 dist 目录。后面的 check:dts / check:ssr 依赖构建产物 yarn build # 在本地浏览器跑测试Jasmine Karma。按需选一个 yarn test:local --browsers ChromeHeadless # or to run in Firefox yarn test:local --browsers FirefoxHeadless # or to run in both yarn test:local # 检查发行版的 TypeScript 声明 yarn check:dts # 检查包是否兼容 server-side rendering yarn check:ssr测试全部通过、check:dts与check:ssr无报错即本地验证完成。提交 PR 与 BrowserStack 注意事项本地检查通过后创建 PR。文档给出几条与测试相关的限制提交前需要知道可以创建 draft PR 让 GitHub Actions 自动跑检查BrowserStack 上的浏览器测试要等 FingerprintJS 维护者批准后才会运行从 fork 仓库提交的 PR 不会自动跑 BrowserStack 测试需要维护者手动触发BrowserStack 会话不稳定即使没有与测试相关的明确错误会话也可能无故失败——看不到明确报错时重跑测试即可不要并行运行多个测试命令否则 BrowserStack 会丢失与 Karma server 的连接导致测试无限挂起一次只跑一个测试命令。如果你没有 BrowserStack 访问密钥文档也提供了替代路径直接向仓库提 PR由 CI 自动跑 BrowserStack 测试受上面审批规则约束。需要本地跑 BrowserStack 时的命令是your-username、your-key需替换为你自己的 BrowserStack 账号凭据适用于 Linux、macOS 和 WSLBROWSERSTACK_USERNAMEyour-username BROWSERSTACK_ACCESS_KEYyour-key yarn test:browserstackPR 被合并的判定标准仍然是开头列出的规则检查全绿、测试覆盖新代码、改动最小且向后兼容。熵源列表本身不受 Semantic Versioning 约束见 src/sources/index.ts 中sources的注释所以新增一个熵源不会要求 bump 小版本或大版本但 visitor identifier 的取值会随之变化这正是它进入sources后对所有用户的实际影响。【免费下载链接】fingerprintjsThe most advanced free and open-source browser fingerprinting library项目地址: https://gitcode.com/GitHub_Trending/fi/fingerprintjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考