{"id":19072899,"url":"https://github.com/lzwme/get-physical-address","last_synced_at":"2025-04-28T18:53:58.662Z","repository":{"id":41522075,"uuid":"487949495","full_name":"lzwme/get-physical-address","owner":"lzwme","description":"Try get the physical address(hardware MAC address) of the hosts network interfaces.","archived":false,"fork":false,"pushed_at":"2023-12-25T08:17:10.000Z","size":107,"stargazers_count":12,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-18T19:39:05.876Z","etag":null,"topics":["electron","lzwme","mac","mac-address","nodejs","physical-address"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lzwme.png","metadata":{"files":{"readme":".github/README_zh-CN.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-05-02T18:29:02.000Z","updated_at":"2025-04-13T12:50:54.000Z","dependencies_parsed_at":"2025-04-18T07:43:20.216Z","dependency_job_id":"6dd026a0-c1a8-4331-bd36-9c5a09ad7ae5","html_url":"https://github.com/lzwme/get-physical-address","commit_stats":{"total_commits":23,"total_committers":1,"mean_commits":23.0,"dds":0.0,"last_synced_commit":"02fa28433536065754dbfa7b6954aa5d61de00fb"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzwme%2Fget-physical-address","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzwme%2Fget-physical-address/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzwme%2Fget-physical-address/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzwme%2Fget-physical-address/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lzwme","download_url":"https://codeload.github.com/lzwme/get-physical-address/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251372457,"owners_count":21578960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron","lzwme","mac","mac-address","nodejs","physical-address"],"created_at":"2024-11-09T01:44:32.526Z","updated_at":"2025-04-28T18:53:58.656Z","avatar_url":"https://github.com/lzwme.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![@lzwme/get-physical-address](https://nodei.co/npm/@lzwme/get-physical-address.png)][npm-url]\n\n# @lzwme/get-physical-address\n\n[![build status](https://github.com/lzwme/get-physical-address/actions/workflows/node-ci.yml/badge.svg?branch=main)](https://github.com/lzwme/get-physical-address/actions/workflows/node-ci.yml)\n[![NPM version][npm-badge]][npm-url]\n[![node version][node-badge]][node-url]\n[![npm download][download-badge]][download-url]\n[![GitHub issues][issues-badge]][issues-url]\n[![GitHub forks][forks-badge]][forks-url]\n[![GitHub stars][stars-badge]][stars-url]\n![license MIT](https://img.shields.io/github/license/lzwme/asmd-calc)\n\n获取本机物理网卡 Mac 地址。过滤虚拟机网卡、VPN 虚拟网卡等，返回真实的物理网卡 Mac 地址信息。\n\n## 背景\n\n在 `Node.js` 或 `Electron` 应用中，可能会需要根据 Mac 地址和 IP 地址作为识别设备唯一性的重要标记，并据此作为建立用户设备黑名单/白名单机制的依据。\n\n通过 Node.js 提供的 API `os.networkInterfaces()` 可以很方便的获得设备网卡信息。\n\n但当用户机器上开启了虚拟机、VPN 等时，该 API 返回的网卡数量可能会非常多，此时需要识别真实的物理网卡，以保证在无论是否使用了虚拟网卡上网方式，都能准确的返回唯一物理网卡的信息，以避免识别出现误差而导致误判。\n\n为了尽可能的获取真实物理网卡信息，可以使用的手段主要有：\n\n- 通过常见虚拟机厂商的 Mac 地址前缀过滤。厂商设备 Mac 地址前缀列表参考： https://standards-oui.ieee.org/oui/oui.txt\n- 通过系统命令获取网卡描述，按关键字过滤(windows)\n  - `ipconfig /all` for windows\n  - `wmic nic get` for windows\n- 按 Mac 地址、IP 地址格式排序优先级\n- more...\n\n## 安装\n\n```bash\nnpm i @lzwme/get-physical-address\n# use yarn\nyarn add @lzwme/get-physical-address\n```\n\n## 使用\n\n示例：\n\n```ts\nimport { getNetworkIFaceOne, getMac } from '@lzwme/get-physical-address';\n\ngetNetworkIFaceOne().then(item =\u003e {\n  console.log(`isVirtualMac: ${isVirtualMac(item.mac, item.desc)}. the MAC address is ${item.mac}, the IP address is ${item.address}`);\n});\n\ngetMac().then(mac =\u003e console.log(`the MAC address is ${mac}`));\ngetMac('en0').then(mac =\u003e console.log(`the MAC address for en0 is ${mac}`));\n```\n\n更多 API 使用示例：\n\n```ts\nimport { isMac, hasMac, isValidMac, isVirtualMac, formatMac, getAllPhysicsMac } from '@lzwme/get-physical-address';\n\nisMac('aa-bb-cc-dd-ee-ff'); // true\nhasMac('The MAC address is aa-bb-cc-dd-ee-ff'); // true\nisMac('00:00:00:00:00:00'); // true\nisValidMac('00:00:00:00:00:00'); // false\nformatMac('AA-BB-CC-DD-EE-FF'); // aa:bb:cc:dd:ee:ff\nisVirtualMac('00:0c:29:ae:ce'); // true\n\ngetAllMac().then(list =\u003e console.log(list));\ngetAllPhysicsMac('IPv4').then(list =\u003e console.log(list));\n```\n\n## API\n\n### `getMac`\n\n- `getMac(iface?: string): Promise\u003cstring\u003e`\n- `getAllPhysicsMac(family?: 'IPv4' | 'IPv6'): Promise\u003cstring[]\u003e`\n- `getAllMac(): string[]` 仅过滤 `internal=true` 和 MAC 地址为 0 的项\n\n### `getNetworkInterface`\n\n- `getNetworkIFaces(iface?: string, family?: 'IPv4' | 'IPv6'): Promise\u003cos.NetworkInterfaceInfo[]\u003e`\n- `getNetworkIFaceOne(iface?: string): Promise\u003cos.NetworkInterfaceInfoIPv4 | os.NetworkInterfaceInfoIPv6\u003e`\n\n### `utils`\n\n- `isMac(mac: string): boolean`\n- `hasMac(str: string): boolean`\n- `isZeroMac(mac: string): boolean`\n- `isValidMac(mac: string): boolean`\n- `formatMac(mac: string): string`\n\n## 开发\n\n本地二次开发：\n\n```bash\ngit clone https://github.com/lzwme/get-physical-address\nyarn install\nnpm link\nyarn dev\n```\n\n或者 [fork](https://github.com/lzwme/get-physical-address/network) 本项目进行代码贡献。\n\n**欢迎贡献想法与代码。**\n\n## License\n\n`@lzwme/get-physical-address` is released under the MIT license.\n\n该插件由[志文工作室](https://lzw.me)开发和维护。\n\n[stars-badge]: https://img.shields.io/github/stars/lzwme/get-physical-address.svg\n[stars-url]: https://github.com/lzwme/get-physical-address/stargazers\n[forks-badge]: https://img.shields.io/github/forks/lzwme/get-physical-address.svg\n[forks-url]: https://github.com/lzwme/get-physical-address/network\n[issues-badge]: https://img.shields.io/github/issues/lzwme/get-physical-address.svg\n[issues-url]: https://github.com/lzwme/get-physical-address/issues\n[npm-badge]: https://img.shields.io/npm/v/@lzwme/get-physical-address.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/@lzwme/get-physical-address\n[node-badge]: https://img.shields.io/badge/node.js-%3E=_12.0.0-green.svg?style=flat-square\n[node-url]: https://nodejs.org/download/\n[download-badge]: https://img.shields.io/npm/dm/@lzwme/get-physical-address.svg?style=flat-square\n[download-url]: https://npmjs.org/package/@lzwme/get-physical-address\n[bundlephobia-url]: https://bundlephobia.com/result?p=@lzwme/get-physical-address@latest\n[bundlephobia-badge]: https://badgen.net/bundlephobia/minzip/@lzwme/get-physical-address@latest\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flzwme%2Fget-physical-address","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flzwme%2Fget-physical-address","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flzwme%2Fget-physical-address/lists"}