貢獻指南

啟動專案

步驟 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 每次執行開發腳本時都會建立新設定檔。 **

如果你希望在開發會話之間保留登入狀態、已安裝的開發工具擴充功能和瀏覽器設置，可以在根目錄建立或修改 web-ext.config.ts。

不同系統的持久化配置寫法略有不同：

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

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

Windows 上 WXT 文件建議使用 chromiumProfile 和 keepProfileChanges。注意 chromiumProfile 必須是絕對路徑，可以用 node:path 的 resolve 產生。

好處： 設定檔在開發會話間保持，所以你可以：

安裝開發工具擴充
記住登入狀態
保持瀏覽器設定

💡 提示： 持久化設定檔只適用於 Chromium 瀏覽器。可以取代範例中的 .wxt/chrome-data，為每個項目使用獨立的組態目錄。

開發模式下的 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

macOS: 開啟檔案過多錯誤 (EMFILE)

如果你在 macOS 上執行 pnpm dev 時遇到此錯誤：

Emfile Error

這是因為 Chokidar（Vite/WXT 使用的檔案監聽函式庫）預設使用 macOS 的原生檔案系統事件（FSEvents），需要為每個監聽的檔案/目錄開啟一個檔案描述子。大型專案可能會超出系統限制。

解決方案： 設定 CHOKIDAR_USEPOLLING=true 改用輪詢模式偵測檔案變化，不需要檔案描述符。

在專案根目錄中建立或更新 .env 檔案：

# .env
CHOKIDAR_USEPOLLING=true

這樣以後直接 pnpm dev 就可以了，不用每次手動加環境變數。

注意： 輪詢模式稍微慢一點，CPU 佔用稍高，但可以避免檔案描述子限制的問題。

提交程式碼

建立新的分支

# 如果是新功能
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

WXT 會依照 Vite 的約定讀取 dotenv 檔案。需要在擴充代碼中透過 import.meta.env 存取的變量，請使用 WXT_ 前綴。

如果只是暫時為某個指令設定環境變量，不同系統的寫法不同：

SKIP_FREE_API=true pnpm test

Windows 預設 Shell 不支援 KEY=value command 這種 macOS/Linux 寫入法。如果遇到類似指令無法執行，請改用上面的 PowerShell 或 CMD 寫入；長期使用的 WXT 環境變數優先放在 .env.development 中。

在中國大陸跳過谷歌測試

如果你是中國大陸貢獻者，那麼當你要 push 代碼的時候你得用

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