教程：迁移到 Manifest V2

Manifest V1 已在 Chrome 18 中弃用，根据 清单版本 1 支持时间表。从版本 1 到版本 2 的更改分为 宽泛类别：API 更改和安全性更改。

本文档提供了有关将 Chrome 扩展程序从清单版本 1 迁移到 随后将详细说明这些变更的含义和变更原因。

API 变更核对清单

  • 您使用的是 browser_actions 属性还是 chrome.browserActions API？

  • 将 browser_actions 替换为单数 browser_action 属性。

  • 将 chrome.browserActions 替换为 chrome.browserAction。

  • 将 icons 属性替换为 default_icon。

  • 将 name 属性替换为 default_title。

  • 将 popup 属性替换为 default_popup（现在它必须是字符串）。

  • 您使用的是 page_actions 属性还是 chrome.pageActions API？

  • 将 page_actions 替换为 page_action。

  • 将 chrome.pageActions 替换为 chrome.pageAction。

  • 将 icons 属性替换为 default_icon。

  • 将 name 属性替换为 default_title。

  • 将 popup 属性替换为 default_popup（现在它必须是字符串）。

  • 您是否使用了 chrome.self 属性？

  • 替换为 chrome.extension。

  • 您是否使用了 Port.tab 属性？

  • 替换为 Port.sender。

  • 您使用的是chrome.extension.getTabContentses()还是 chrome.extension.getExtensionTabs() API？

  • 替换为 chrome.extension.getViews( { "type" : "tab" } )。

  • 您的扩展程序是否使用了后台网页？

  • 将 background_page 属性替换为 background 属性。

  • 添加包含网页代码的 scripts 或 page 属性。

  • 添加 persistent 属性并将其设置为 false，以将后台网页转换为事件 页面

安全性变更核对清单

  • 是否在 HTML 页面中使用内嵌脚本块？

  • 移除 <script> 标记中包含的 JS 代码，并将其放置在外部 JS 文件中。

  • 您是否使用了内嵌事件处理脚本（如 onClick 等）？

  • 将其从 HTML 代码中移除，将其移至外部 JS 文件中，然后使用 addEventListener() 。

  • 您的扩展程序是否会将内容脚本注入需要访问资源（如 图片和脚本）？

  • 定义 web_accessible_resources 属性并列出资源（以及 单独的内容安全政策）。

  • 您的扩展程序是否嵌入了外部网页？

  • 定义 sandbox 属性。

  • 是您的代码或库使用的是 eval()、新的 Function()、innerHTML、setTimeout() 还是 否则传递动态评估的 JS 代码字符串？

  • 如果要将 JSON 代码解析为对象，请使用 JSON.parse()。

  • 使用支持 CSP 的库，例如 AngularJS。

  • 使用以下命令，在您的清单中创建一个沙盒条目，并在沙盒中运行受影响的代码： postMessage()，用于与沙盒化网页通信。

  • 您是否加载了外部代码，例如 jQuery 或 Google Analytics？

  • 建议您下载该库并将其打包到扩展程序中，然后从 本地软件包。

  • 在“content_security_policy”中将提供资源的 HTTPS 网域列入许可名单部分 清单。

API 变更摘要

清单版本 2 对浏览器操作 API 和网页操作 API 引入了一些更改， 一些旧 API 和新 API。

浏览器操作发生变化

浏览器操作 API 引入了一些命名变更：

  • browser_actions 和 chrome.browserActions 属性已替换为各自的 单数对应 browser_action 和 chrome.browserAction。

  • 在旧的 browser_actions 属性下，有 icons、name 和 popup 属性。 这些内容已被替换为：

  • default_icon：表示浏览器操作标记图标

  • default_name：将鼠标悬停在标记上时提示中显示的文本

  • default_popup，适用于表示浏览器操作界面的 HTML 页面（现在必须 为字符串，但不能是对象）

网页操作发生变化

与浏览器操作的变化类似，页面操作 API 也发生了变化：

  • page_actions 和 chrome.pageActions 属性已替换为其单数形式。 与 page_action 和 chrome.pageAction 相对应。

  • 在旧的 page_actions 属性下，有 icons、name 和 popup 属性。这些 已被替换为：

  • default_icon：网页操作标记图标

  • default_name：将鼠标悬停在标记上时提示中显示的文本

  • default_popup - 适用于表示网页操作界面的 HTML 网页（现在，它必须为 字符串，但不能是对象）

移除和更改的 API

一些扩展程序 API 已被移除，取而代之的是新的对应项：

  • background_page 属性已替换为 background。
  • chrome.self 属性已移除，请使用 chrome.extension。
  • Port.tab 属性已替换为 Port.sender。
  • chrome.extension.getTabContentses() 和 chrome.extension.getExtensionTabs() API 具有 已替换为 chrome.extension.getViews( { "type" : "tab" } )。

安全性变更摘要

在从清单版本 1 迁移到 版本 2。其中许多变化源于 Chrome 采用了内容安全政策；您 您应详细了解此政策，了解其影响。

不允许使用内嵌脚本和事件处理脚本

由于使用了内容安全政策，您无法再使用内嵌的 <script> 标记 与 HTML 内容相关联。这些必须移至外部 JS 文件中。此外，内联事件处理脚本 也不受支持。例如，假设您的扩展程序中包含以下代码：

<html>
<head>
  <script>
    function myFunc() { ... }
  </script>
</head>
</html>

此代码会导致运行时出错。若要解决此问题，请将 <script> 标记内容移至外部文件 并使用 src='path_to_file.js' 属性引用它们。

类似地，内联事件处理脚本是许多常见的事件处理脚本和便捷功能， 网络开发者，不会执行。以下面这些常见情况为例：

<body onload="initialize()">
<button onclick="handleClick()" id="button1">

这些不适用于 Manifest V2 扩展程序。删除内嵌事件处理脚本，将其放在 外部 JS 文件，并改用 addEventListener() 为其注册事件处理脚本。对于 例如，在您的 JS 代码中，使用以下代码：

window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);

通过这种方法，您可以更清晰地将扩展程序的行为与其界面标记分离开来。

嵌入内容

在某些情况下，您的扩展程序可能会嵌入可在外部使用或 来自外部来源

网页中的扩展程序内容： 如果您的扩展程序嵌入了内容中使用的资源（例如图片、脚本、CSS 样式等） 注入到网页的脚本，您需要使用 web_accessible_resources 属性 将这些资源列入许可名单，以便外部网页可以使用它们：

{
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

嵌入外部内容： 内容安全政策仅允许从您的文件包加载本地脚本和对象， 可防止外部攻击者向您的扩展程序引入未知代码。不过， 当您需要加载外部提供资源（例如 jQuery 或 Google Analytics 代码）时。 您可以采用下列两种方法：

  1. 在本地下载相关库（如 jQuery），并将其与您的扩展程序打包在一起。

  2. 您可以通过在 &quot;content_security_policy&quot;部分。要添加像 Google Analytics 这样的库 可采用以下方法：

    {
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}

使用动态脚本评估

也许新的 Manifest v2 方案最大的变化之一就是，扩展程序无法再 使用动态脚本评估技术（如 eval()）或新的 Function()，或传递 JS 字符串 添加到会导致使用 eval() 的函数中，例如 setTimeout()。此外，某些 常用的 JavaScript 库（例如 Google Maps）和某些模板库， 运用其中的一些技术

Chrome 为网页提供了一个沙盒，供其在自己的源中运行，而不允许其访问 Chrome。* API。若要根据新的内容安全政策使用“eval()”等内容，请执行以下操作：

  1. 在您的清单文件中创建一个沙盒条目。
  2. 在测试区条目中，列出您要在测试区中运行的网页。
  3. 使用通过 postMessage() 的消息传递功能与沙盒化页面进行通信。

如需详细了解如何执行此操作，请参阅沙盒评估文档。

深入阅读

清单版本 2 中的变化旨在指导开发者构建更安全、更可靠的 架构完善的扩展程序和应用查看清单版本 1 中的完整更改列表 到版本 2，请参阅清单文件文档。详细了解如何使用沙盒 要隔离不安全的代码，请阅读沙盒评估一文。如需详细了解内容 安全策略，请访问与扩展程序相关的教程以及有关 HTML5Rocks。