全栈攻城狮

Appearance

package.json 详解 ​

package.json 是插件的清单文件，承载了插件的全部「声明式能力」：何时激活、贡献哪些命令与菜单、依赖哪个版本的 VS Code。理解它是插件开发的第一课。

字段总览 ​

脚手架生成的核心字段：

字段必填作用
name是插件唯一标识（小写字母数字）
displayName否市场中显示的名称
description否插件描述
version是语义化版本号
publisher是发布者 ID
engines是兼容的 VS Code 版本
main是入口文件
activationEvents是激活事件列表
contributes否能力贡献点
scripts否构建脚本

engines.vscode 版本约束 ​

声明插件兼容的 VS Code 最低版本：

json
{
  "engines": {
    "vscode": "^1.85.0"
  }
}

要点：

  • 使用高版本 API 时，必须提高此约束
  • 版本过低，API 调用会运行时失败
  • 市场按此字段过滤可安装版本

配置发布者 publisher ​

发布者标识插件归属，发布到市场前必须设置：

json
{
  "publisher": "your-org-name"
}
  • 与 Azure DevOps 组织的 Publisher ID 一致
  • 一个 publisher 可发布多个插件
  • 未设置前仅可本地开发调试

激活事件 activationEvents ​

activationEvents 声明插件何时被激活（加载并执行 activate()）。VS Code 采用懒加载，只有事件发生时插件才被加载。

事件类型 ​

事件触发时机
onCommand:命令ID执行指定命令时
onLanguage:语言ID打开指定语言文件时
onView:视图ID指定视图可见时
onCustomEditor:类型打开自定义编辑器时
onWebviewPanel:类型创建 Webview 面板时
onFileSystem:scheme访问指定文件系统时
onUri打开插件的 URI 时
onStartupFinishedVS Code 启动完成后
*启动时立即激活（不推荐）

示例 ​

json
{
  "activationEvents": [
    "onCommand:myExt.hello",
    "onLanguage:markdown"
  ]
}

自动激活优化 ​

从 VS Code 1.74 起，大部分场景可以省略 activationEvents：

  • 声明了 contributes.commands 的命令，自动获得 onCommand 激活
  • 声明了 contributes.views 的视图，自动获得 onView 激活
  • 语言相关的贡献点自动注册

只有需要 onStartupFinished、onUri 等特殊事件时才显式声明。尽量让激活事件最小化，插件只在需要时加载。

贡献点 contributes ​

contributes 声明插件向 VS Code 贡献的能力，覆盖全部编辑器扩展点：

贡献点用途
commands注册命令
menus注册菜单项
keybindings注册快捷键
configuration注册设置项
views / viewsContainers注册视图/容器
customEditors注册自定义编辑器
languages注册语言
grammars注册 TextMate 语法高亮
snippets注册代码片段
themes注册颜色/图标主题
debuggers注册调试器
jsonValidationJSON 校验
breakpoints断点类型
typescriptServerPluginsTS Server 插件
walkthroughs引导教程
authentication认证提供者
localizations本地化

commands 示例 ​

json
{
  "contributes": {
    "commands": [
      {
        "command": "myExt.helloWorld",
        "title": "Hello World",
        "category": "My Extension"
      }
    ]
  }
}

声明后命令出现在命令面板中，配合 activationEvents 的 onCommand 在首次执行时激活插件。

json
{
  "contributes": {
    "menus": {
      "editor/context": [
        {
          "command": "myExt.transform",
          "when": "editorHasSelection"
        }
      ]
    }
  }
}

configuration 示例 ​

json
{
  "contributes": {
    "configuration": {
      "title": "My Extension",
      "properties": {
        "myExt.enable": {
          "type": "boolean",
          "default": true,
          "description": "是否启用功能"
        }
      }
    }
  }
}

完整示例 ​

一份典型插件的 package.json：

json
{
  "name": "my-extension",
  "displayName": "My Extension",
  "description": "A sample extension",
  "version": "0.0.1",
  "publisher": "my-org",
  "engines": {
    "vscode": "^1.85.0"
  },
  "categories": ["Other"],
  "activationEvents": [
    "onCommand:myExt.helloWorld"
  ],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "myExt.helloWorld",
        "title": "Hello World",
        "category": "My Extension"
      }
    ]
  },
  "scripts": {
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./"
  },
  "devDependencies": {
    "@types/vscode": "^1.85.0",
    "typescript": "^5.0.0"
  }
}

常见问题 ​

问题处理
命令面板找不到命令检查 contributes.commands 与激活事件
插件不激活检查 activationEvents 是否覆盖触发场景
API 报类型错误提升 engines.vscode 与 @types/vscode 版本
发布失败提示缺 publisher补全 publisher 字段

掌握 package.json 的声明能力，插件的「骨架」就立起来了，接下来是编写激活函数与业务逻辑。