如果只从功能上看，GitZip Pro 做的事情很直接：用户打开 GitHub 仓库页面，勾选想要下载的文件或文件夹，然后点击下载，扩展把这些内容打包成一个 zip 文件交给浏览器下载。

但从源码角度看，这个过程并不是一个简单的“按钮点击事件”。它背后至少包含四个运行面：注入 GitHub 页面的 content script、负责后台能力的 background service worker、承载设置项的 options 页面，以及用于快速查看状态的 popup 页面。第一篇先不深入下载细节，而是从扩展入口出发，建立 GitZip Pro 的整体源码地图。

GitZip Pro

项目目录
项目的核心源码集中在 source 目录：

source/
manifest.json
constants.js
i18n.js
jszip.min.js
downloader.js
content.js
content.css
background.js
popup.html
popup.js
options.html
options.js
options_init.js
locales/
_locales/
icons/
根目录下还有构建脚本和发布相关文件：

build.js
package.json
BUILD.md
README.md
chrome-web-store-description.md
chrome-web-store-permission-justifications.txt
所以读这个项目时，可以先把它分成两层：source 是扩展运行时源码，根目录的 build.js 和 package.json 是构建发布层。

整体架构图
manifest.json
扩展装配入口

content scripts
constants / i18n / jszip / downloader / content

background.js
后台 service worker

popup.html + popup.js
扩展弹窗

options.html + options.js
设置页面

web_accessible_resources
可被页面访问的资源

GitHub 仓库页面
注入选择框和下载按钮

downloader.js
解析 URL / 请求 GitHub API / 打包 zip

右键菜单 / 通知 / 消息通信

chrome.storage.local
主题 / token / 规则 / 历史

GitHub API

这张图基本就是 GitZip Pro 的运行骨架。manifest.json 不直接实现业务逻辑，但它决定了哪些脚本会在什么环境中加载。content.js 运行在 GitHub 页面上下文附近，负责改造页面；downloader.js 是下载引擎；background.js 处理右键菜单和通知；options.js 管理设置、token、历史记录和统计；popup.js 则是扩展图标弹窗里的轻量入口。

manifest.json：扩展的装配说明书
GitZip Pro 使用 Manifest V3：

{
“manifest_version”: 3,
“name”: “GitZip Pro”,
“version”: “1.1.3”,
“default_locale”: “en”,
“description”: “GitZip for GitHub, but Pro.”
}
这个文件最重要的不是名称和版本，而是它把扩展拆成了几个运行区域。

首先是权限：

“permissions”: [
“storage”,
“tabs”,
“downloads”,
“notifications”,
“contextMenus”,
“identity”
]
这些权限和后面的模块是一一对应的。storage 用来保存设置、token、下载历史；downloads 用来触发浏览器下载；notifications 用来显示下载结果；contextMenus 对应右键菜单；identity 服务于 GitHub 授权相关流程；tabs 则让扩展能读取和操作当前标签页上下文。

然后是 host 权限：

“host_permissions”: [
“https://github.com/",
"https://gitzip-pro-worker.fthux.com/”
]
这说明 GitZip Pro 的主要工作场景是 GitHub 页面，同时还会访问一个扩展自己的 worker 服务。结合后面的源码可以看到，GitHub 页面增强发生在 content.js，GitHub API 请求发生在 downloader.js，而授权相关能力会牵涉到 options 页面中的 token 配置逻辑。

content_scripts：真正进入 GitHub 页面的一组脚本
manifest.json 里最关键的配置是 content_scripts：

“content_scripts”: [
{
“matches”: [“https://github.com/*”],
“js”: [
“constants.js”,
“i18n.js”,
“jszip.min.js”,
“downloader.js”,
“content.js”
],
“css”: [“content.css”],
“run_at”: “document_idle”
}
]
这个加载顺序很值得注意。constants.js 最先加载，因为后面的模块都需要公共配置；i18n.js 提供翻译能力；jszip.min.js 提供 zip 打包能力；downloader.js 提供下载引擎；最后才是 content.js，它负责把前面的能力接到 GitHub 页面上。

换句话说，GitZip Pro 的页面侧运行链路大致是：

JSZip
GitHub API
downloader.js
content.js
GitHub Page
manifest.json
JSZip
GitHub API
downloader.js
content.js
GitHub Page
manifest.json
在 github.com 注入脚本和样式
扫描仓库文件列表
注入选择框和下载按钮
用户选择文件或文件夹
传入选中项并启动下载
请求文件树和文件内容
写入 zip
生成压缩包并触发下载
这里有一个很清晰的分工：content.js 不应该关心 GitHub API 细节，它只负责页面交互和选中项收集；downloader.js 不应该关心 DOM，它只负责把 GitHub 文件路径变成实际的 zip 内容。

constants.js：跨模块共享的配置中心
constants.js 使用一个立即执行函数把配置挂到 globalThis.GZP_CONSTANTS 上。它主要包含几类内容。

第一类是 storage key：

const STORAGE_KEYS = {
THEME: ‘gzpTheme’,
GITHUB_TOKEN: ‘gzpGitHubToken’,
TOKEN_ACCESS_MODE: ‘gzpTokenAccessMode’,
DOWNLOAD_HISTORY: ‘gzpDownloadHistory’,
LANGUAGE: ‘gzpLocale’
};
第二类是默认设置，例如主题、按钮位置、命名规则、通知开关、语言等。第三类是 URL 配置，包括 GitHub、GitHub API、项目仓库地址和 OAuth worker。第四类是下载限制：

const DOWNLOAD = {
CONCURRENCY_LIMIT: 5,
MAX_FILE_COUNT: 500
};
这两个值会影响下载器行为：并发数量不能无限放大，文件数量也不能无限递归。第一篇只需要知道它们属于全局配置，具体如何在 downloader.js 中使用，会在后面的下载核心篇展开。

constants.js 里还有多浏览器商店配置：

const EXTENSION_STORES = {
chrome: CHROME_WEBSTORE,
firefox: { … },
edge: { … }
};
这和构建脚本有关。项目不是只面向 Chrome，而是预留了 Chrome、Firefox、Edge 三个渠道。

background.js：后台能力入口
background.js 被声明为 service worker：

“background”: {
“service_worker”: “background.js”,
“scripts”: [“background.js”]
}
它不负责页面 DOM，也不负责 zip 打包。它的核心职责更像扩展的后台控制层：初始化国际化、创建右键菜单、响应安装事件、处理消息、显示通知。

从源码结构看，background.js 启动后会先执行 initBackgroundI18n，加载语言包，然后调用 ensureContextMenus 创建或更新右键菜单。菜单项包括根菜单、下载已勾选项目、下载当前右键选中的项目等。这样用户不一定非要点击页面上的浮动下载按钮，也可以通过浏览器右键菜单触发部分能力。

popup 与 options：两个不同的界面入口