Chrome扩展开发教程：权限模型详解，permissions与host_permissions区别

本节目标：学完你能从”两条轴”的视角看懂权限模型，分清 permissions 与 host_permissions 的根本区别，识别 matches 与宿主权限的混淆，并清楚每项权限背后要付的代价。

第 10 章已经把权限的写法、常用权限名都过了一遍。这一章换个视角：把权限当成一套”模型”来理解，而不是一份要背的清单。模型只有两条轴，外加两个常见的坑和一份代价清单。想清楚这些，任何具体权限你都能自己推导。

23-1 从两条轴理解权限模型

权限模型的起点是两条轴：API 轴管”扩展能调用哪些浏览器接口”，宿主轴管”扩展能访问哪些网址的内容”。后面所有权限知识，都是这两条轴的具体展开。

先看一份完整的声明（和第 10 章 §10-1 同一份，不重复解释）：

{
  "name": "Permissions Extension",
  "version": "1.0",
  "manifest_version": 3,
  "permissions": [
    "activeTab",
    "contextMenus",
    "storage"
  ],
  "optional_permissions": [
    "topSites"
  ],
  "host_permissions": [
    "https://www.developer.chrome.com/*"
  ],
  "optional_host_permissions": [
    "https://*/*",
    "http://*/*"
  ]
}

四个数组怎么填、optional 系列怎么用，第 10 章和后面两章分别展开；这里只记住：它们全部落在两条轴上。

23-2 权限模型的两条轴：API 轴与宿主轴

这是全节最关键的一点，我多说几句。

权限模型本质上只有两条轴。第一条是 API 轴，回答”扩展能调用哪些浏览器接口”；第二条是宿主轴，回答”扩展能访问哪些网址的内容”。理解这两条轴，后面所有权限都不会乱。

API 轴（permissions）：横向的能力开关，和”具体哪个网站”无关。比如 storage 让你用 chrome.storage 存数据，contextMenus 让你加右键菜单，alarms 让你设定时任务。它是一种”你有没有这个能力”的判定。
宿主轴（host_permissions）：纵向的范围授权，针对网站来源。比如你声明了 https://www.developer.chrome.com/*，扩展就能对该站发起跨域请求、读取其页面信息、在内容脚本里与之交互。它是一种”你对哪些网站拥有权限”的判定。

一句话区分：permissions 是”能做什么动作”，host_permissions 是”能在哪些网站上做”。 两者经常要配合使用。例如内容脚本要注入到某站并读取其 DOM，既要在 content_scripts.matches 里匹配该站，通常还要在 host_permissions 里声明该站（取决于具体 API）。

Note

权限是”先声明、后使用”。代码里调用了一个没声明的接口，运行时报的往往是模糊错误，排查起来很费劲。所以写代码前先想清楚要用哪些能力，把清单补齐。

23-3 常用权限名：如第 10 章所述

storage、activeTab、scripting、tabs、cookies、downloads 这些常用权限名各自代表什么能力、哪些会触发安装警告，第 10 章 §10-3 列过一张清单，这里不再重复。

在权限模型里，它们全部属于 API 轴上的开关。挑权限时记住一个判断：这个能力是不是”用户明确要用的核心功能”？是，就上主权限；只是偶尔用到的进阶能力，就丢进 optional 系列（第 24 章）。

23-4 host_permissions：宿主轴的取舍

宿主轴要回答的是：扩展到底需要”长期、自动”地访问哪些网站。比如一个翻译扩展要在后台静默抓取目标网页内容，或一个比价扩展要读取电商页面，这些站才值得写进 host_permissions。

具体写法（匹配模式、<all_urls> 的代价）见第 10 章 §10-5 和第 17 章。这里只说模型的结论：宿主权限是”向用户借来的信任”，借得越少、用得越准。 能用 activeTab 临时授权解决的场景，就不要申请长期宿主权限——这正是 23-6 要讲的权衡。

23-5 一个常见混淆：host_permissions 和 matches 不是一回事

这里有个坑，初学者特别容易踩。content_scripts 里的 matches 和清单顶层的 host_permissions 听起来都和”网站”有关，但它们不是一回事。

matches：决定”脚本注入哪些页面”，是注入范围。它告诉浏览器”遇到这些网址就自动塞进一段内容脚本”。
host_permissions：决定”扩展对该站拥有哪些跨域/读取能力”，是权限范围。它告诉浏览器”这个扩展被允许和这些站点打交道”。

举个例：你在 matches 里写了 https://a.com/*，内容脚本会被注入 a.com，但如果你没有在 host_permissions 里声明 a.com，后台用 fetch 去读 a.com 的数据仍可能被拦。反过来，有了 host_permissions 不代表脚本会自动注入——注入还得靠 matches 或 scripting.executeScript。两者是”注入”和”权限”两个维度，别混为一谈。

23-6 activeTab：临时授权的代表

activeTab 是”临时授权”思路的代表：用户主动唤起扩展时（点工具栏按钮、执行命令、点右键菜单），扩展才在”当前这个标签页”上临时获得访问权，不需要任何宿主权限。它的完整用法和代码示例见第 10 章 §10-4。

这里只补一个容易误解的细节：授权不会因为你切走标签就收回。 它在你导航离开当前页面、或关闭这个标签时才失效；切到别的标签再切回来，授权依然有效。所以”点一下按钮、切走再切回、再注入一次”的连续操作，activeTab 也扛得住。

23-7 常用权限清单与”何时需要”

名字在第 10 章列过，这里给一张”什么时候该用哪个”的判断表，写清单前对照着想一遍：

只是存点本地设置/状态 → storage。几乎必选，无警告。
用户点按钮后才动当前页面（染红、划词、填表） → activeTab + scripting，不走宿主权限。
要在后台自动读/改某些固定网站 → 这些站写进 host_permissions，且能收窄就收窄。
读标签页的网址、标题做展示 → tabs。但要清醒：它读不到页面正文。
要操作书签、Cookie、下载、历史 → 分别对应 bookmarks/cookies/downloads/history。这些都是敏感权限，会触发警告，确认功能确实需要再放。
拦截或改写网络请求 → declarativeNetRequest，MV3 唯一正规途径。
弹系统通知、加右键菜单、开侧边栏 → 对应 notifications/contextMenus/sidePanel。

Note

判断的底层逻辑就一句：这个权限是”用户明确要用的核心功能”才上主权限；是”偶尔才用到的进阶能力”就丢进 optional 系列（第 24 章）。别因为有就都写进 permissions。

23-8 安装警告横幅与权限的代价

最后提醒一个现实问题：权限不是免费的。清单里每多一项敏感权限，用户安装时看到的警告就多一条。history、tabs、bookmarks、cookies、<all_urls> 这类都会触发明显风险提示。

警告本身没错，它是浏览器在帮用户把关。但警告太多会带来两个后果：一是普通用户看到一长串风险就直接放弃安装；二是商店审核会更仔细地审视”你凭什么要这些权限”，功能对不上的容易被打回。

所以权限概述这一节的结论很简单：把权限当成一种”向用户借来的信任”，借得越少、用得越准，扩展越容易活得好。下一章我们讲 optional_permissions，看怎么把”锦上添花”的权限推迟到用户真正用到时才开口要。