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

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

设置页由三个文件组成：

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

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

(async function initOptionsPage() {
  await GZP_I18N.init();
  GZP_I18N.applyTranslations();
})();

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

设置页整体结构

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

const themeSelect = document.getElementById('themeSelect');
const languageSelect = document.getElementById('languageSelect');
const buttonPositionSelect = document.getElementById('buttonPositionSelect');
const namingPreset = document.getElementById('namingPreset');
const githubToken = document.getElementById('githubToken');
const historyContent = document.getElementById('history-content');
const statsOverviewGrid = 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：

const C = globalThis.GZP_CONSTANTS;
const STORAGE = C.STORAGE_KEYS;
const DEFAULTS = C.DEFAULTS;

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

function applyTheme(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。它们对应常见忽略场景，例如版本控制目录、依赖目录、构建产物、日志文件等。

用户选中的预设保存在：

let activeLabels = new Set();

用户自定义规则保存在：

let customRules = [];

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

STORAGE.IGNORE_LABELS
STORAGE.IGNORE_CUSTOM_VARS

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

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

GitHub Token 设置

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

const TOKEN_STORAGE_KEY = STORAGE.GITHUB_TOKEN;
const TOKEN_MODE_KEY = STORAGE.TOKEN_ACCESS_MODE;
const TOKEN_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 是：

const HISTORY_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」版。