ahwayakchih/crx3
GitHub: ahwayakchih/crx3
CRX3是一个Node.js工具，用于创建适用于Chromium系列浏览器的网页扩展包。
Stars: 73 | Forks: 6
# CRX3
此模块允许您为 Chromium、Google Chrome 以及所有其他支持该文件格式和 API 的浏览器（例如 Opera）创建网页扩展文件。
它创建的是 CRXv3 文件，适用于 Chrome 64.0.3242 及以上版本。
如果您需要为不支持 CRXv3 的旧版浏览器创建网页扩展文件，请改用 [CRX 模块](https://github.com/oncletom/crx)。
它需要 Node.js 22 版本（或更高）或 Bun 1.2.18 版本（或更高），并可在 Linux、MacOS 和 Windows 上运行。
[](https://github.com/ahwayakchih/crx3/actions/workflows/test.yml "Linux、MacOS 和 Windows 构建日志")
[](https://github.com/ahwayakchih/crx3/actions/workflows/puppeteer-container.yml "Puppeteer 容器构建与测试日志")
## 安装
要安装 CRX3 以供常规使用，如同大多数其他 Node.js 模块一样，请使用以下命令行：
```
npm install --omit=dev crx3
```
或进行全局安装：
```
npm install -g --omit=dev crx3
```
如果您想参与 CRX3 模块的开发，请克隆模块仓库（参见 [API 文档](#generating-api-documentation)）并使用以下命令行代替上面的：
```
npm install
```
## 用法（CLI）
如果您已全局安装 CRX3，或正尝试在项目的 `package.json` 脚本中使用它，您应该能像这样使用：
```
crx3 web-extension-directory
```
它支持以下选项：
- *-z, --zip, --zipPath*：同时创建一个包含网页扩展文件的简单 ZIP 文件
- *-o, --crx, --crxPath*：为 CRX3 文件指定自定义路径名
- *-p, --key, --keyPath*：为私钥文件指定自定义路径名
- *-x, --xml, --xmlPath*：为 XML（更新清单）文件指定自定义路径名
- *--forceDateTime* ：指定用于新 ZIP 文件内容的 UNIX 时间戳
- *--appVersion* ：指定要写入更新清单文件的版本号
- *--crxURL* ：指定要写入更新清单文件的 URL
- *--browserVersion* ：指定运行网页扩展所需的最低浏览器版本
如果任何 `*Path` 选项后面没有跟随路径或文件名，输出文件名将基于网页扩展的目录名。
如果私钥文件已存在，则不会创建新的。将使用现有的那个。
CRX、ZIP 和 XML 文件总是会被覆盖。
`--forceDateTime` 是可选的，仅在创建新 ZIP 文件时使用。
`--appVersion`、`--crxURL` 和 `--browserVersion` 仅用于写入 XML 文件。
例如：
```
crx3 -p -o -x -z some-other-name.zip web-extension
```
它将创建 "web-extension.pem"（如果尚不存在）、"web-extension.crx"、"web-extension.xml" 和 "some-other-name.zip" 文件。
**警告**：如果您使用不带名称/路径的选项，它必须在带名称/路径的选项之前指定。否则，请确保要包含在网页扩展文件中的目录和/或文件列表是在特殊的 `--` 标记之后指定的，如下所示：
```
crx3 -z some-other-name.zip -x -o -- web-extension
```
如果您已有一个包含网页扩展文件的 ZIP 文件，您可以像这样使用 CRX3：
```
cat web-extension.zip | crx3 -p web-extension.pem
```
它将把现有的 ZIP 文件转换为 "web-extension.crx" 文件，并创建一个 "web-extension.pem" 文件。
确保 ZIP 文件内容没有父目录，例如，"manifest.json" 文件必须直接存在，而不是 "web-extension/manifest.json"。
否则，新的 CRX 文件将无法在浏览器中工作。
**警告**：CRX3 不会读取 ZIP 文件的内容。这意味着，为了让可选的 XML 文件正常工作，必须指定 `APP_VERSION` 环境变量或 `--appVersion` 参数。否则 XML 文件将包含 "`${APP_VERSION}`" 占位符。
`CRX_URL`/`--crxURL` 和 `BROWSER_VERSION`/`--browserVersion` 值同理。
您也可以动态创建 ZIP 文件，并像这样传递：
```
zip -r -9 -j - web-extension | crx3 -p web-extension.pem
```
## 用法（API）
这是一个如何使用此模块的快速示例：
```
const crx3 = require('crx3');
crx3(['example/example-extension/manifest.json'], {
keyPath: 'example/example-extension.pem',
crxPath: 'example/example-extension.crx',
zipPath: 'example/example-extension.zip',
xmlPath: 'example/example-extension.xml',
crxURL : 'http://127.0.0.1:8080/example-extension.crx'
})
.then(() => console.log('done'))
.catch(console.error)
;
```
您可以在 [ahwayakchih.github.io/crx3](https://ahwayakchih.github.io/crx3/) 在线阅读完整的 API 文档。
## 已知问题
### CRX_REQUIRED_PROOF_MISSING（Chrome 和 Chromium）
从 75.x 版本开始，Chrome 要求扩展文件上有 Google 网上应用店的签名。CRX3 模块不提供这些签名（这需要访问 Google 的私钥）。以下信息是通过检查 Chromium 源代码“猜测”得出的：
- https://github.com/chromium/chromium/blob/c48c9b176af94f7ec65e20f21594524526d2a830/components/crx_file/crx_verifier.cc#L178 仅当公共密钥或“必需密钥”缺失时才会返回错误。
- https://github.com/chromium/chromium/blob/c48c9b176af94f7ec65e20f21594524526d2a830/components/crx_file/crx_verifier.cc#L134 和 https://github.com/chromium/chromium/blob/c48c9b176af94f7ec65e20f21594524526d2a830/components/crx_file/crx_verifier.cc#L42 “必需密钥”似乎是他们预定义的密钥。
所以，我有可能搞错了，如果是这样，请不要犹豫，就此创建一个新的 [issue](https://github.com/ahwayakchih/crx3/issues)。
除非扩展是通过 `chrome://extensions/` 页面安装的，并且事先启用了“开发者模式”（需要先启用，然后必须重启 Chrome），否则用户在尝试安装使用 CRX3 模块创建的 `.crx` 文件时，很可能会看到 `CRX_REQUIRED_PROOF_MISSING` 错误。
另请注意，同一个 CRX 文件在通过 Google 管理员面板部署时应该仍然可以正常安装（如 [issue#2](https://github.com/ahwayakchih/crx3/issues/2#issuecomment-3896526363) 的评论中所报告）。
有关托管自定义 CRX 扩展所需更改的更多信息，请参见：
https://developer.chrome.com/docs/extensions/mv2/hosting-changes?hl=en#deployment
### 从 CRX 安装扩展
在 MacOS 和 Windows 上，Chrome 不再允许从本地文件安装扩展（通过策略安装除外）。
有关手动安装自定义扩展的更多信息，请参见：
https://developer.chrome.com/docs/extensions/how-to/distribute/install-extensions
在 MacOS 或 Linux 上，可以通过[首选项文件](https://developer.chrome.com/docs/extensions/how-to/distribute/install-extensions#preferences)安装扩展，只要：
- 其 `manifest.json` 文件中的 [`update_url`](https://developer.chrome.com/docs/extensions/how-to/distribute/host-on-linux#update_url) 值是正确的，
- 它来自具有[正确设置](https://developer.chrome.com/docs/extensions/how-to/distribute/host-on-linux#hosting)的服务器。
在 Windows 上，可以通过 [Windows 注册表](https://developer.chrome.com/docs/extensions/how-to/distribute/install-extensions#registry)安装。
在所有系统上，扩展都可以通过策略设置安装：
- 参见如何操作：https://www.chromium.org/administrators/configuring-policy-for-extensions，
- 参见可配置的策略：https://www.chromium.org/administrators/policy-list-3。
## 开发
### 生成 API 文档
要为此模块生成文档，请像这样从仓库克隆模块（NPM 包不包含所需文件）：
```
git clone https://github.com/ahwayakchih/crx3.git
```
然后，在克隆的目录中（`cd crx3` 进入目录），使用以下命令：
```
npm run doc
```
它应该会在本地的 `./reports/jsdoc/` 子目录中创建文件。
### 编写网页扩展
要编写扩展，请为 Chrome/Chromium 使用 [Extension API](https://developer.chrome.com/extensions)，为 Mozilla 浏览器使用 [WebExtensions API](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions)。它们非常相似，因此可以创建一个适用于所有浏览器的扩展（只需将其构建为不同的扩展文件格式 - 对于 Mozilla，您可以使用 https://github.com/mozilla/web-ext）。
### 测试
要运行测试，请克隆模块（参见 [API 文档](#generating-api-documentation)）并使用：
```
npm test
```
或者，当使用 bun 运行时：
```
bun run test
```
测试包括可选支持，用于检查模块构建的 CRX 文件是否能在 Linux 系统的 Chromium 浏览器中运行。要使其工作：
- 确保 Chrome 或 Chromium 浏览器已安装，
- 确保 `CHROME_BIN` 环境变量已设置为浏览器可执行文件的路径，
- 确保 `CHROME_POLICIES` 环境变量指向浏览器用于读取策略的现有目录树，
- 可选择将 `DEBUG` 环境变量设置为 `true`，以从测试服务器获取额外输出，
- 可选择将 `FILE_CHECK_DELAY` 环境变量设置为各项检查之间等待的毫秒数（默认为 1500），
- 运行 `npm run puppeteer` 以安装额外的依赖项。
如果未指定 `CHROME_POLICIES`，默认使用 `/etc/chromium/policies`。如果使用的是 Google Chrome，这将**不起作用**，如 Chromium 的 [Linux 快速入门](https://www.chromium.org/administrators/linux-quick-start/)中所述。
**警告：** 由于无法通过 puppeteer 模拟 CRX 文件的安装过程（或者有办法？），测试将尝试创建一个 `${CHROME_POLICIES}/managed/crx3-example-extension-test.json` 策略文件来“强制安装”它。这就是为什么最好在虚拟机中运行整个过程，例如使用 [`qemu`](https://www.qemu.org/)，或在容器中运行，例如使用 [`podman`](https://podman.io/) 或 [`docker`](https://www.docker.com/)。
有一个官方的 puppeteer docker 镜像，但它大约 2 GB，大得没有必要。使用 `podman` 或 `docker`，您可以构建一个大小不到一半的镜像，这足以测试生成的 CRX3 是否能在 Chromium 浏览器中工作。
#### 使用 [无根 `podman`](https://github.com/containers/podman/blob/main/README.md#rootless) 进行测试
第一步是准备容器镜像。此步骤只需进行一次。
```
# 1. 准备容器，此步骤只需执行一次
podman build -t puppeteer -f puppeteer.containerfile
# 2. 安装 puppeteer-core，此步骤只需执行一次
podman run --rm --init -v $(pwd):/app -w /app --userns=keep-id:uid=1000,gid=1000 -it puppeteer:latest npm run puppeteer
```
容器镜像准备好后，每次您想运行测试时，只需使用：
```
podman run --rm --init -v $(pwd):/app -w /app --userns=keep-id:uid=1000,gid=1000 -it puppeteer:latest xvfb-run npm test
```
标签：Bun 运行时, Chromium 支持, CRX3 文件创建, DNS解析, Google Chrome 扩展, Linux 操作系统, MacOS 操作系统, MITM代理, Node.js 22 兼容, Node.js 模块, Opera 浏览器, SOC Prime, Web 扩展打包, Windows 操作系统, 代码生成, 命令行界面, 开发工具, 开源项目, 扩展版本 v3, 批量测试, 数据可视化, 文件格式处理, 浏览器扩展开发, 渗透测试工具, 自定义脚本, 跨平台工具, 软件包管理