贡献指南

启动项目

步骤 1: Fork 项目并克隆到本地

# 从你的 fork 克隆项目
git clone https://github.com/xxxxx/read-frog.git

# 进入项目目录
cd read-frog

# 添加上游仓库以便与原始仓库同步
git remote add upstream https://github.com/mengxi-ream/read-frog.git

步骤 2: 安装依赖并启动开发

# 安装依赖
pnpm i

# 启动开发服务器
pnpm dev

这将启动扩展开发环境。扩展会自动在你的默认浏览器中打开。

开发 Tips

使用 pnpm Node.js 管理时的 npx 问题

我们正在使用 pnpm 的内置 Node.js 版本管理功能(在 pnpm 10.14 中引入)。运行 npx 命令时可能会遇到 EBADDEVENGINES 错误。有两种解决方案:

方案 1: 使用 pnpm dlx 或 pnpx 替代 npx

# 以前用 npx
npx some-package@latest

# 现在用 pnpm dlx
pnpm dlx some-package@latest

# 或使用 pnpx (pnpm dlx 的别名)
pnpx some-package@latest

方案 2: 使用 pnpm 对齐 Node.js 版本

当不方便替换 npx 命令时(例如 Claude Code 的用户级 MCP 安装),可以对齐 Node.js 版本:

# 全局安装并使用所需的 Node.js 版本
pnpm env use --global 22.18.0

在特定浏览器中打开扩展

你可以创建或修改根目录下的 web-ext.config.ts 文件，显式指定浏览器路径。

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  binaries: {
      chrome: "path/to/your/chrome.exe",
      firefox: "path/to/your/firefox.exe",
      edge: "path/to/your/edge.exe"
    }
});

pnpm dev 无法自动加载扩展

如果你使用 Chrome 137 或更高版本，你需要下载 Chrome for Testing 进行开发。请参考详细说明。

持久化 Chrome 配置文件

默认情况下，web-ext 每次运行开发脚本时都会创建新配置文件。

只有 Chromium 浏览器支持使用 --user-data-dir 标志创建持久化配置文件：

export default defineWebExtConfig({
  chromiumArgs: ['--user-data-dir=./.wxt/chrome-data'],
});

好处： 配置文件在开发会话间保持，所以你可以：

安装开发工具扩展
记住登录状态
保持浏览器设置

💡 提示： 可以为 --user-data-dir 使用任何目录。当前配置为每个项目创建配置文件。

开发模式下的 Google 登录问题

如果你想在开发模式下使用 Google 账号登录，但遇到错误 "This browser or app may not be secure."（此浏览器或应用可能不安全），你需要禁用自动化检测。

解决方法： 在 web-ext.config.ts 中添加 chromiumArgs：

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  chromiumArgs: ['--disable-blink-features=AutomationControlled'],
});

这将禁用自动化检测，避免 Google 阻止来自自动化浏览器的登录请求。

断点调试问题

⚠️ 如果你遇到了无法断点调试的问题，可能是因为 Chrome DevTools 的 ignore list 设置。扩展注入的内容脚本可能被自动忽略，导致断点失效。

解决方法：

打开任意网页的 Devtools
点击右上角设置图标（⚙️）
在左侧导航中选择 "Ignore list"
确保 "Content scripts injected by extensions" 选项未勾选

Chrome Ignore List

提交代码

创建新的分支

# 如果是新功能
git checkout -b feat/the-feature

# 如果是修复 bug
git checkout -b fix/the-bug

# 如果是文档调整
git checkout -b docs/the-docs

分支合并

当远程分支(main)更新时，会导致我们的 Pull Request 存在冲突，你可以通过提前合并远程分支来解决

# 切到 main 分支 
git checkout main

# 同步上游仓库
git pull upstream main

# 切回开发分支
git checkout docs/xxxx

# 同步远程分支
git rebase main

# 如果 rebase 后还有冲突，推送一次
git push --force-with-lease origin docs/xxxx

# 如果没有冲突，推送代码
git push origin docs/xxxx

Fatal in syncing the upstream repository

如果你在同步上游仓库时遇到该错误

fatal: 'upstream' does not appear to be a git repository
fatal: Could not read from remote repository.

这意味着在步骤 1 中没有配置 upstream remote。现在添加它：

git remote add upstream https://github.com/mengxi-ream/read-frog.git

发起 Pull Request

发起 Pull Request 前，需要先添加 changeset 来记录你的改动。

理解版本升级类型

根据你的改动选择合适的版本升级类型：

patch - Bug 修复、错别字、文档更新、小的改进
- 示例：修复翻译错误、更新 README、修复按钮样式、性能改进
minor - 向后兼容的新功能
- 示例：添加禁用翻译按钮、添加词汇导出功能
major - 影响现有功能的破坏性更改
- 示例：更改 API 结构、删除已弃用的功能、重大重构

添加 Changeset

# 运行 changeset 命令
pnpm changeset

# 1. 为每个选中的 package 选择版本升级类型
🦋  What kind of change is this for @read-frog/extension? (current version is 1.17.3)
❯ patch   # Bug 修复和小的改进
  minor   # 新功能
  major   # 破坏性更改

# 2. 编写改动摘要
🦋  Please enter a summary for this change (this will be in the changelog)
Summary >>> fix: translation button style

运行 pnpm changeset 后，会在 .changeset 目录中生成一个 markdown 文件。在创建 Pull Request 前，你可以编辑该文件以提供更多改动细节。

然后创建 Pull Request 并等待合并。

Commit 规范

我们使用 Conventional Commits 规范来编写 commit message。

设置环境变量

在开发扩展时，为了自动加载环境变量，例如开发环境的 API 密钥，您可以在根目录中创建一个 .env.development 文件。

# .env.development
WXT_OPENAI_API_KEY=xxx
WXT_DEEPSEEK_API_KEY=xxx

在中国大陆跳过谷歌测试

如果你是中国大陆贡献者，那么当你要 push 代码的时候你得用

# MAC
SKIP_FREE_API=true git push

# WINDOWS
$env:SKIP_FREE_API='true'
git push

为什么要这样做呢？因为在你 push 代码的时候会做代码测试，但是谷歌的免费 API 在国内无法访问，这会导致测试失败，从而 push 失败，我们通过设置 SKIP_FREE_API 环境变量来跳过谷歌测试。

什么样的 PR 会被审核并合并？

刚开始贡献

如果这是你的前几个 PR，主要态度认真，一般不会因为 PR 质量问题而的不到合并。维护者会帮助你找出问题并让你适应我们的开发流程，代码风格等。但是我们强烈建议你遵循以下规则：

尽可能小的问题入手，比如仓库中的 Good First Issue，这样小而简单的 PR 能让你有一个平滑的学习过程。
确保你的 PR 通过了所有 GitHub Actions 和本地的测试。

为什么我的 PR 迟迟得不到维护者审核？

在你还没有熟悉代码仓库的时候，贡献了过于复杂的 PR，导致 PR 有太多需要修改的地方。
你的代码出现了很多低级错误，维护者怀疑你的态度不认真
- 未删除很多并未被使用的代码片段
- 大量的重复性代码
- 变量和函数命名过于随意
- 我们鼓励 AI 协助开发，但是你没有仔细通读 AI 的代码，导致大量低质量不可维护或者过度设计代码混入
如果维护者提供了几次的修改意见，但是发现你并没有按照修改意见进行修改，或者修改了但是没有解决根本问题。

On this page