• 入门
• 概述
• 新功能
• 开发者指南
  • 用户界面
    • 浏览器按钮
    • 右键菜单
    • 桌面通知
    • 多功能地址栏
    • 选项页面
    • 代替页面
    • 页面按钮
  • 浏览器交互
    • 书签
    • Cookies
    • 开发人员工具
    • 事件
    • 历史记录
    • 管理
    • 标签页
    • 窗口
  • 实现
    • 辅助功能
    • 事件页面
    • 内容安全策略(CSP)
    • 内容脚本
    • 跨站XMLHttpRequest
    • 国际化
    • 消息传递
    • 可选权限
    • NPAPI插件
  • 完成
    • 托管
    • 其他部署方案
• 教程
  • 清单文件V2
  • 调试
  • Google Analytics(分析)
  • OAuth
• 参考
  • 格式
    • 清单文件
    • 匹配表达式
  • 权限警告
  • chrome.* APIs
  • 其他APIs
• 更多
  • chrome商店
  • 托管应用程序
  • 主题

格式: 清单文件

每一个扩展程序、可安装的网络应用程序以及主题背景都有一个 JSON格式的清单文件，名为manifest.json, 提供重要信息。

字段概述

如下代码展示了支持的清单文件字段，以及讨论每一个字段的链接。只有 name 和 version字段是必需的。

{
  // 必选
  "name": "我的扩展程序",
  "version": "版本字符串",
  "manifest_version": 2,

  // 推荐
  "description": "纯文本描述",
  "icons": { ... },
  "default_locale": "en",

  // 从中选一个（或者没有）
  "browser_action": {...},
  "page_action": {...},
  "theme": {...},
  "app": {...},

  // 添加您需要的
  "background": {"persistent": false, ...},
  "background": {"persistent": true, ...},
  "chrome_url_overrides": {...},
  "content_scripts": [...],
  "content_security_policy": "policyString",
  "file_browser_handlers": [...],
  "homepage_url": "http://path/to/homepage",
  "incognito": "spanning" or "split",
  "intents": {...}
  "key": "publicKey",
  "minimum_chrome_version": "versionString",

  "nacl_modules": [...],
  "offline_enabled": true,
  "omnibox": { "keyword": "aString" },
  "options_page": "aFile.html",
  "permissions": [...],
  "plugins": [...],
  "requirements": {...},
  "update_url": "http://path/to/updateInfo.xml",
  "web_accessible_resources": [...],
  "sandbox": [...]
}

字段详情

这一部分包含了其它页面中没有描述的字段。有关字段的完整列表以及指向描述它们细节的页面链接，请参见 字段概述。

app

用于打包应用程序 ，指定应用程序的后台脚本； 也用于托管应用程序 ，指定应用程序使用的URL。

default_locale

指定_locales中的子目录，包含该扩展程序默认字符串。对于含有_locales目录的扩展程序来说这一属性是必需的，在没有_locales目录的扩展程序中该属性不能存在。有关更多细节，请参见国际化支持。

description

描述该扩展程序的纯文本字符串（不能包含HTML或其它格式化内容，不要超过132个字符）。描述应该同时适合在浏览器的扩展程序管理用户界面以及 Chrome网上应用店中显示。您可以在该字段中指定语言相关的字符串，有关细节请参见 国际化支持。

homepage_url

该扩展程序的主页URL。扩展程序管理页面（chrome://extensions或chrome://settings/extensionSettings）将包含指向该URL的链接。如果您 在您自己的网站上托管扩展程序，该属性将十分有用。如果您通过 Chrome网上应用店发布您的扩展程序，主页URL默认为扩展程序自己的页面。

icons

一个或多个代表扩展程序、应用程序或主题背景的图标。您应该确保提供一个128×128大小的图标，用与安装过程中以及Chrome网上应用店。扩展程序同时应该提供一个48×48大小的图标，用于扩展程序管理页面（chrome://extensions或chrome://settings/extensionSettings）。您也可以再指定一个16×16大小的图标，用于扩展程序页面的收藏夹图标，16×16的图标也将显示在实验性的扩展程序 信息栏 中。

通常图标应该使用PNG格式，因为PNG格式对透明度的支持最佳。但图标也可以是其它任何WebKit支持的格式，包括BMP、GIF、ICO和JPEG。如下是一个指定图标的例子：

"icons": { "16": "icon16.png",
           "48": "icon48.png",
          "128": "icon128.png" },

重要提示： 只能使用文档中规定的图标大小。

您可能注意到Chrome有时候会缩小这些图标。例如，安装对话框可能将128像素的图标缩小至69像素。

然而，Chrome浏览器用户界面的细节可能会在不同版本间更改，并且这些更改假定开发者使用了文档中规定的大小。如果您使用其它大小，您的图标在将来版本的浏览器中可能会看起来效果不佳。

如果您使用 Chrome开发者信息中心上传您的扩展程序、应用程序或主题背景，您还需要上传额外的图像，包括至少一张您的扩展程序的屏幕截图。有关更多信息，请参见 CChrome网上应用店开发者文档。

incognito

可以是"spanning"或"split"，指定该扩展程序如果允许在隐身模式中运行时会如何表现。

对于扩展程序来说默认值为"spanning"，意味着扩展程序将会在单个共享进程中运行，任何来自隐身标签页的事件或消息都将发送至共享的进程，以 incognito标志指示它的来源。由于隐身标签页无法使用这一共享进程，使用"spanning"隐身模式的扩展程序不能将扩展程序包中的页面载入到隐身标签的主框架。

对于可安装的网络应用程序来说默认值为"split"，意味着隐身窗口中的所有应用程序页面将会在它们自己的隐身进程中运行。如果应用程序或扩展程序包含后台页面，它们也会在隐身进程中运行。隐身进程与普通进程同时运行，但是使用单独的仅保留在内存中的Cookie存储区。每一个进程只能接收到来自它自己上下文的事件与消息（例如，隐身进程只会看到隐身标签页的更新）。两个进程之间无法互相通信。

选择的准则是，如果您的扩展程序或者应用程序需要在隐身模式下载入标签页，使用 split隐身行为。如果您的扩展程序或应用程序需要登录远程服务器或者在本地保留设置，使用spanning 隐身模式。

intents

指定这一扩展程序或应用程序提供的所有Intent处理程序的词典，词典中的每一个键指定这一扩展程序处理的动作谓语。以下例子为动作谓语 "http://webintents.org/share"指定两个处理程序。

{
  "name": "测试",
  "version": "1",
  "intents": {
    "http://webintents.org/share": [
      {
        "type": ["text/uri-list"],
        "href": "/services/sharelink.html",
        "title" : "Sample Link Sharing Intent",
        "disposition" : "inline"
      },
      {
        "type": ["image/*"],
        "href": "/services/shareimage.html",
        "title" : "Sample Image Sharing Intent",
        "disposition" : "window"
      }
    ]
  }
}

"type"的值为这一处理程序支持的MIME类型数组，"href"指示处理该Intent的页面URL。对于托管应用程序，这些URL必须包含在允许的URL中。对于扩展程序，所有URL必须在扩展程序中，并且认为相对于扩展程序根URL。

当用户执行这一处理程序的操作时"title"将在Intent选择器用户界面中显示。

"disposition"可以为"inline"或"window"。使用"window"方式的Intent调用时将打开新标签页，而使用"inline"方式调用时会显示在Intent选择器中。

有关Intent的更多信息，请参考Web Intents规范与webintents.org。

通过Intent处理内容类型

Web Intents可以注册为内容类型的查看器，如果要这么做，动作谓语必须为 "http://webintents.org/view"，内容类型必须为白名单中的MIME类型。

key

这一值用来控制在开发过程中载入的扩展程序、应用程序或主题背景的唯一标识符。

注意：通常您不需要使用这一值。相反，您应该使用 相对路径 以及chrome.extension.getURL()来编写不依赖这一值的代码。

要获得合适的键值，首先从.crx文件安装您的扩展程序（您可能需要 上传您的扩展程序 或手工打包）。然后，在您的 配置文件目录，查看如下文件： Default/Extensions/<extensionId>/<versionString>/manifest.json， 您将会看到填在此处的键值。

minimum_chrome_version

您的扩展程序、应用程序或主题背景需要的Chrome浏览器版本，如果有任何要求的话。该字符串的格式与 version 字段相同。

name

一个较短的纯文本字符串（不超过45个字符）标志该扩展程序。名称将在安装对话框、扩展程序管理用户界面以及 Chrome网上应用店. 中使用。您可以为该指定语言相关的字符串，有关细节请参见国际化支持。

nacl_modules

一个或多个从MIME类型至Native Client模块的映射，用来处理这些类型。例如，如下片段中的加粗代码将一个Native Client模块注册为OpenOffice电子表格MIME类型的内容处理器。

{
  "name": "Native Client OpenOffice 电子表格查看器",
  "version": "0.1",
  "description": "直接在您的浏览器中打开 OpenOffice 电子表格。",
  "nacl_modules": [{
    "path": "OpenOfficeViewer.nmf",
    "mime_type": "application/vnd.oasis.opendocument.spreadsheet"
  }]
}

"path"的值为扩展程序目录中Native Client清单文件（一个.nmf文件）的位置。有关Native Client以及 .nmf文件的更多信息，请参见 Native Client技术概述.

每一个MIME类型只能与一个.nmf文件关联，但是一个.nmf文件可以处理多个MIME类型。如下例子演示一个扩展程序，含有两个.nmf文件，处理三种MIME类型。

{
  "name": "电子表格查看器",
  "version": "0.1",
  "description": "直接在您的浏览器中打开 OpenOffice 和 Excel 电子表格。",
  "nacl_modules": [{
    "path": "OpenOfficeViewer.nmf",
    "mime_type": "application/vnd.oasis.opendocument.spreadsheet"
  },
  {
    "path": "OpenOfficeViewer.nmf",
    "mime_type": "application/vnd.oasis.opendocument.spreadsheet-template"
  },
  {
    "path": "ExcelViewer.nmf",
    "mime_type": "application/excel"
  }]
}

注意: 您不指定"nacl_modules"也能在扩展程序中使用Native Client模块，只有当您需要浏览器使用您的Native Client模块显示特定类型的内容时才需要使用"nacl_modules"。

offline_enabled

应用程序或者扩展程序能否在离线状态下工作。当Chrome浏览器检测到处于离线状态时，这一属性设为true的应用程序会在新标签页面中高亮显示。

permissions

扩展或应用程序可能会使用到的一组权限。 每一个权限既可以是已知字符串列表中的某一个（例如"geolocation"），也可以是授予访问一个或多个主机权限的匹配表达式。权限可以帮助您在扩展程序或应用程序受到攻击时尽可能减小损失，某些权限也会在安装前向用户显示，这些将在 权限警告中详细描述。

如果某个API需要您在清单文件中声明某个权限，它的文档会告诉你如何去做。例如， 标签页面 会向您演示如何声明"tabs"权限。

注意: 在Chrome 16后, 一些权限是可选的。 请查看 可选权限了解更多详情。

如下是一个扩展程序清单文件的权限部分的例子：

"permissions": [
  "tabs",
  "bookmarks",
  "http://www.blogger.com/",
  "http://*.google.com/",
  "unlimitedStorage"
],

下面表格中列出的权限只能在扩展或者打包的应用程序中可以使用。

注意： 托管应用程序只能使用 "background", "clipboardRead", "clipboardWrite", "geolocation", "notifications", 及 "unlimitedStorage"权限，而不能使用下表列出的所有其它权限

<img src="chrome://favicon/http://www.google.com/">

requirements

应用程序或扩展程序要求的技术。托管站点（例如Chrome网上应用店）可能会使用这一列表建议用户不要安装不能在他们的计算机上工作的应用程序或者扩展程序。目前支持的要求包括"3D"与"plugins"（插件），将来还可能增加其它要求检查。

"3D"要求代表GPU硬件加速。 "webgl"要求指的是 WebGL API。 有关Chrome浏览器对3D图形支持的更多信息，请参见有关 WebGL和3D图形. 的帮助文章。您可以列出您的应用程序要求的3D相关功能，如以下例子所示：

"requirements": {
  "3D": {
    "features": ["webgl"]
  }
}

"plugins"（插件）要求表示应用程序或扩展程序是否需要NPAPI才能运行。默认情况下，当清单文件包含 "plugins"字段时将启用该要求。对于插件不可用时仍能正常工作的应用程序与扩展程序，您可以将NPAPI设置为false，禁用这一要求。您也可以手工启用该要求，将NPAPI设置为true，如以下例子所示：

"requirements": {
  "plugins": {
    "npapi": true
  }
}

version

一至四个用点（半角英文句号）分开的整数，标识扩展程序的版本。这些整数应该符合这两条规则：范围在0-65535之间（包括0和65535），非零整数不能以0开头。例如99999和032都是无效的。

如下是一些有效的版本号的例子：

• "version": "1"
• "version": "1.0"
• "version": "2.10.2"
• "version": "3.1.2.4567"

自动更新系统比较版本号来确定已安装的某个扩展程序是否需要更新。如果已发布的扩展程序比已安装的扩展程序有更新的版本字符串，该扩展程序将会自动更新。

比较将从最左边的整数开始。如果相等，比较右边的整数，以此类推。例如，1.2.0比1.1.9.9999新。

省略整数的等于零，例如1.1.9.9999比1.1新。

有关更多信息，请参见 自动更新.

manifest_version

指定您的扩展程序包要求的清单文件格式的版本。从Chrome 18开始，开发人员 应该指定2 （不加引号），使用本文档描述的格式：

"manifest_version": 2

从Chrome 18开始，认为清单文件版本1已弃用， 版本2目前还不是必需的, 但是我们在不远的将来某一时刻，将不再支持使用已弃用清单文件版本的扩展程序包。还没有准备转换至Chrome 18中新的清单文件版本的扩展程序、应用程序以及主题背景既可以明确地指定版本1，也可以完全省略该属性。

清单文件格式版本1与版本2之间的改变在 manifest_version文档中详细描述。

不建议在Chrome 17或更低版本中设置manifest_version 2 。如果您的扩展程序需要在较旧版本的Chrome浏览器中运行，目前请继续使用版本1，在版本1停止工作前我们将会给出充分的警告。

web_accessible_resources

字符串数组，指定扩展程序包内可以在网页中使用的资源路径（相对于扩展程序包的根目录）。例如，为了在 example.com上建立自定义界面，而插入内容脚本的扩展程序可以将界面需要的所有资源（图片、图标、样式表、脚本等等）加入白名单，如下所示：

{
  ...
  "web_accessible_resources": [
    "images/my-awesome-image1.png",
    "images/my-amazing-icon1.png",
    "style/double-rainbow.css",
    "script/double-rainbow.js"
  ],
  ...
}

这些资源将可以通过 chrome-extension://[PACKAGE ID]/[PATH]使用，URL可以通过 chrome.extension.getURL 方法产生。加入白名单的资源将以合适的 CORS头信息提供，所以它们可以通过XHR之类的机制使用。

插入的内容脚本本身不需要加入白名单。

在清单文件版本2之前，扩展程序内的所有资源都可以从任何网页中访问，这样恶意网站就能收集用户已安装扩展程序的 指纹信息或者利用扩展程序中的漏洞（例如 XSS漏洞）。将资源访问限制为明确需要可以通过网络访问的那些，有助于尽可能减小可用的攻击层面，并保护用户的隐私。

默认情况

使用manifest_version 2或更高的扩展程序包内的资源默认情况下被阻止，必须通过这一属性加入白名单。

使用manifest_version 的扩展程序包内的资源默认情况下可用，但是 只要您设置了这一属性，它将以所有加入白名单资源的完整列表来对待，没有列出的资源将被阻止。

sandbox

要在受沙箱保护的唯一来源中载入的页面路径（相对于扩展程序包根目录）列表，还可以指定可选的内容安全策略来一起使用。在沙箱中意味着如下两点：

1. 受沙箱保护的页面不能访问扩展程序或应用程序API，也不能直接访问沙箱外的页面（但是可以通过 postMessage()进行通信）。

2. 受沙箱保护的页面不受应用程序或扩展程序其余部分使用的 内容安全策略（CSP） 所限制。这就意味着，它可以使用内嵌脚本与 eval.

   例如，如下代码指定两个扩展程序页面将在沙箱中载入，并指定了自定义的CSP：

   {
     ...
     "sandbox": {
       "pages": [
         "page1.html",
         "directory/page2.html"
       ]
       // 内容安全策略是可选的。
       "content_security_policy":
           "sandbox allow-scripts; script-src https://www.google.com"
     ],
     ...
   }

   如果没有指定的话，默认的content_security_policy值为 sandbox allow-scripts allow-forms。您可以指定您自己的CSP值来更进一步限制沙箱，但是它必须包含sandbox 指示符，并且不能包含allow-same-origin记号（有关可能的沙箱记号，请参照 相应的HTML5规范 ）。

注意，您只需要列出您期望在窗口或框架中载入的页面。受沙箱保护的页面所使用的资源（例如样式表或JavaScript源文件）不需要出现在 sandboxed_page列表中，它们会使用内嵌它们的页面所使用的沙箱。

"安全的使用eval" 文档更详细地介绍了如何实现沙箱保护的工作流程，使您得以使用扩展程序 默认内容安全策略下无法正常执行的库。

只有使用 manifest_version2或更高版本时才能指定受沙箱保护的页面。