GitZip Pro 源码解析：一个 GitHub 文件/文件夹下载扩展是如何工作的（六）设置页、Token 与下载历史

项目地址：fthux/GitZipPro。这一篇聚焦 GitZip Pro 的设置页、GitHub Token、下载历史和统计面板。

前几篇主要围绕 GitHub 页面和下载流程展开。这一篇进入 GitZip Pro 中体量最大的页面：设置页。

设置页由三个文件组成：

source/options.html source/options_init.js source/options.js

其中options_init.js很短，只负责初始化国际化：

(asyncfunctioninitOptionsPage(){awaitGZP_I18N.init();GZP_I18N.applyTranslations();})();

真正的设置逻辑集中在options.js。它既管理普通配置，也管理 GitHub token、忽略规则、下载历史和统计面板。

设置页整体结构

options.js开头会取得大量 DOM 元素：

constthemeSelect=document.getElementById('themeSelect');constlanguageSelect=document.getElementById('languageSelect');constbuttonPositionSelect=document.getElementById('buttonPositionSelect');constnamingPreset=document.getElementById('namingPreset');constgithubToken=document.getElementById('githubToken');consthistoryContent=document.getElementById('history-content');conststatsOverviewGrid=document.getElementById('stats-overview-grid');

这些变量说明设置页不是单一表单，而是多个功能页的组合。

页面菜单切换由activateMenu(target)控制。点击左侧菜单时，它会切换.menu-item的 active 状态，同时展示对应.page。页面也支持 hash 路由，例如#general、#token、#history。

整体结构可以这样理解：

chrome.storage.local是设置页和其他模块之间的共享层。content.js、downloader.js、background.js都会读取其中一部分配置。

基础设置：主题、语言和按钮位置

设置页使用constants.js中的 key：

constC=globalThis.GZP_CONSTANTS;constSTORAGE=C.STORAGE_KEYS;constDEFAULTS=C.DEFAULTS;

主题切换由applyTheme(theme)处理：

functionapplyTheme(theme){if(theme==='system'){document.documentElement.removeAttribute('data-theme');}else{document.documentElement.setAttribute('data-theme',theme);}}

当用户修改主题时，代码会立即应用到当前 options 页面，并写入 storage：

chrome.storage.local.set({[STORAGE.THEME]:theme});

语言切换则会调用GZP_I18N.setLocale()，并触发页面文案刷新。因为 background 也监听了语言 storage 变化，所以右键菜单文案也能跟着更新。

按钮位置、文件大小显示、双击选择等配置也是同样模式：读取默认值，用户修改后写入 storage，content script 后续读取并应用。

下载命名与通知设置

下载相关设置包括：

• NAMING_PRESET
• NAMING_CUSTOM
• NOTIFY_SHOW
• NOTIFY_SOUND
• NOTIFY_OPEN

这些配置最终会被downloader.js的getSettings()读取。也就是说，options 页面本身不参与下载，但它决定下载器如何命名 zip、是否播放提示音、下载完成后是否通知或打开下载项。

命名规则的变量在下载器中被替换：

{owner} {repo} {branch} {path} {date} {datetime} {ts}

设置页负责让用户选择或填写模板，下载器负责在实际下载时用仓库信息替换这些变量。

忽略规则设置

options.js中定义了IGNORE_PRESETS和PRESET_COMBOS。它们对应常见忽略场景，例如版本控制目录、依赖目录、构建产物、日志文件等。

用户选中的预设保存在：

letactiveLabels=newSet();

用户自定义规则保存在：

letcustomRules=[];

当规则变化时，saveIgnoreSettings()会把它们写入：

STORAGE.IGNORE_LABELSSTORAGE.IGNORE_CUSTOM_VARS

下载器后续读取这两个 key，调用compileIgnoreRules()和isIgnored()来过滤文件。

这形成了一个跨模块链路：

GitHub Token 设置

GitZip Pro 支持匿名模式和自定义 token 模式。相关 storage key 包括：

constTOKEN_STORAGE_KEY=STORAGE.GITHUB_TOKEN;constTOKEN_MODE_KEY=STORAGE.TOKEN_ACCESS_MODE;constTOKEN_SCOPE_KEY=STORAGE.TOKEN_SCOPE;

设置页中，用户可以手动输入 token，也可以走 OAuth 流程。OAuth 相关函数包括：

generateCodeVerifier() generateCodeChallenge() getOAuthRedirectUrl() launchIdentityWebAuthFlow() launchPopupOAuthFlow() startGitHubOAuth(scope)

其中generateCodeChallenge()使用crypto.subtle.digest('SHA-256', data)生成 PKCE challenge。这说明 OAuth 流程不是简单跳转，而是带了 PKCE 校验。

token 保存后，downloader.js和content.js都会读取它：

• downloader.js用 token 请求文件和目录内容。
• content.js的文件大小展示也会用 token 请求 GitHub API。

设置页还提供checkRateLimit()，用于查看当前 API rate limit 状态。这部分通过GITHUB_RATE_LIMIT接口判断 token 是否生效。

下载历史

下载历史的 key 是：

constHISTORY_STORAGE_KEY=STORAGE.DOWNLOAD_HISTORY;

历史记录主要由 background 在下载完成后写入。options 页面负责读取、展示、删除和清空。

相关函数包括：

loadHistory() saveHistory() renderHistory() deleteSelectedRecords() clearAllHistory() initHistoryPage()

每条历史记录中包含下载时间、仓库、分支、路径、下载文件名、文件列表、文件数量、被忽略数量等信息。buildHistoryTargetUrl(record)可以根据记录还原 GitHub 目标链接，让用户从历史记录回到对应仓库位置。

当 background 保存历史后，会发送GZP_DOWNLOAD_COMPLETE消息。如果 options 页面打开，就可以实时更新；如果没打开，下次进入页面时也会从 storage 读到。

下载统计

统计面板建立在历史记录之上。核心函数是：

aggregateStats(records) filterHistoryRecords(records) renderStats()

filterHistoryRecords()根据时间范围、类型、仓库、分支、关键词等条件过滤记录。aggregateStats()再计算总下载次数、文件数、被忽略数量、总大小、仓库维度和分支维度。最后renderStats()把结果渲染成 KPI 卡片和表格。

这部分没有重新请求网络，而是完全基于本地历史记录计算。

首次欢迎弹窗

background.js首次安装时会写入：

'gitzip-pro-show-welcome':true

options 页面启动时执行checkAndShowWelcomeModal()。如果检测到首次使用标记，页面会切换到 token 页面，并显示欢迎弹窗。这样首次用户会被引导到最重要的配置区域。

本篇小结

options.js是 GitZip Pro 的配置和数据展示中心。它不直接参与页面注入，也不直接下载文件，但它决定了其他模块的运行方式：

options.js 写入 storage -> content.js 读取 UI 设置 -> downloader.js 读取下载设置和 token -> background.js 写入历史 -> options.js 再读取历史并渲染统计

下一篇是系列最后一篇，收束到popup.js、i18n.js和build.js，看 GitZip Pro 如何处理轻量入口、国际化系统，以及 Chrome / Firefox / Edge 多渠道构建。

完整项目在 fthux/GitZipPro。如果你正在做浏览器扩展的设置页或下载历史功能，可以 Star 后对照源码继续研究。

如果你也好奇这个 Pro 版为什么会做起来，可以接着看这篇项目缘起：用了 GitZip 这么多年，我动手做了一个「Pro」版。