# @codingame/monaco-vscode-api 中文文档

规范地址：https://npmcn.com/package/%40codingame/monaco-vscode-api/

版本：39\.0\.4
npm 元数据更新时间：2026-11-09T13:20:47.520Z
中文译文更新时间：2026-11-10T09:01:13.056Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40codingame/monaco-vscode-api
原文对照：https://npmcn.com/package/%40codingame/monaco-vscode-api/?lang=original
项目主页：https://github.com/CodinGame/monaco-vscode-api#readme
源码仓库：https://github.com/CodinGame/monaco-vscode-api

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：58.6 MB，8013 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：12 个
- 首次发布：2022-06-03T18:45:23.878Z
- 最新版本发布：2026-11-09T13:20:47.100Z
- 近 30 天下载量：688305（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：487（近 12 个月 119 个）

## 中文简介

VSCode 公共 API 插入了 monaco 编辑器

## 安装

```sh
npm install @codingame/monaco-vscode-api
```

也可以使用：`pnpm add @codingame/monaco-vscode-api`、`yarn add @codingame/monaco-vscode-api`、`bun add @codingame/monaco-vscode-api`

## README

# @ codingame/ monaco- vscode- api [![monthly downloads](https://img.shields.io/npm/dm/@codingame/monaco-vscode-api)](https://www.npmjs.com/package/@codingame/monaco-vscode-api) [![npm version](https://img.shields.io/npm/v/@codingame/monaco-vscode-api.svg?style=flat)](https://www.npmjs.com/package/@codingame/monaco-vscode-api) [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/codingame/monaco-vscode-api/pulls)

这个 [国家预防机制模块](https://www.npmjs.com/) 允许将 VSCode 的全部功能整合到您的 `monaco-editor`。 。 。 .

欲了解更多信息,请查看该项目的 [维基百科](https://github.com/CodinGame/monaco-vscode-api/wiki)。 。 。 .

## 安装

```bash
npm install @codingame/monaco-vscode-api
# Optionally install the extension api and the editor api
npm install vscode@npm:@codingame/monaco-vscode-extension-api
npm install monaco-editor@npm:@codingame/monaco-vscode-editor-api
```

`@codingame/monaco-vscode-extension-api` 作为别名安装到 `vscode` 能够运行 `import * as vscode from 'vscode'`,类似于 VSCode 扩展内所做的

`@codingame/monaco-vscode-editor-api` 作为别名安装到 `monaco-editor` 因为它能提供与官方相同的阿皮 `monaco-editor`

# 使用量

如果你刚刚开始 `monaco-editor` 财务报告和审定财务报表 `monaco-vscode-api` 你可能会找到帮助 [获取启动指南](https://github.com/CodinGame/monaco-vscode-api/wiki/Getting-started-guide) 在维基文库中.

## 摩纳哥服务覆盖

大部分VSCode功能作为"服务"被执行,例如.

-   主题服务,为 VSCode 主题提供支持
-   语言服务,为不同的语言特征提供支持.

默认情况下,摩纳哥使用简化版本的VSCode服务,称为 `standalone` 服务. 此软件包允许

1.  用 VSCode 的全功能替代品来覆盖它们
2.  增加摩纳哥未纳入的新服务

以下是以 VSCode json 设置取代摩纳哥默认配置的示例:

```typescript
// default monaco-editor imports
import * as monaco from 'monaco-editor'
import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker'

// utilities to override Monaco services
import { initialize } from '@codingame/monaco-vscode-api'
import getConfigurationServiceOverride, {
  updateUserConfiguration
} from '@codingame/monaco-vscode-configuration-service-override'

window.MonacoEnvironment = {
  getWorker: (_moduleId, _label) => new editorWorker()
}

// overriding Monaco service with VSCode
await initialize({
  ...getConfigurationServiceOverride()
})

// json config like in vscode settings.json
updateUserConfiguration(`{
    "editor.fontSize": 30,
    "editor.lineHeight": 30,
    "editor.fontFamily": "monospace",
    "editor.fontWeight": "bold",
    "editor.letterSpacing": 0,
}`)

// creating an editor with VSCode configuration
monaco.editor.create(document.getElementById('editor')!, {
  value: 'Editor with VSCode config and large bold fonts'
})
```

> \[注\] `initialize` 只能调用一次(在创建您的第一个编辑器之前,应该调用它).

每个 `get<service-name>ServiceOverride` 包含服务和一些胶水,使VSCode服务与摩纳哥合作.

### 服务覆盖列表

一些基础服务覆盖 即将随着这个软件包的依赖性:

-   **基础**数字 : `@codingame/monaco-vscode-base-service-override`
    -   包含一些其他大多数特性必须具备的通用服务
-   **东道主**数字 : `@codingame/monaco-vscode-host-service-override`
    -   与主机/浏览器的互动(shutdown profile,焦点/活性管理,窗口打开,全屏
-   **扩展**数字 : `@codingame/monaco-vscode-extensions-service-override`
    -   支持 VSCode 扩展 .
    -   可以提供工人配置:
        -   然后,网络工人扩展主机将可用,允许运行在 iframe 中的工人运行扩展
-   **文件**数字 : `@codingame/monaco-vscode-files-service-override`
    -   它添加了覆盖文件系统 `file://` 文件,但也添加了对懒惰加载扩展文件的支持。 它添加单独的内存用户文件(例如配置、密钥绑定),缓存文件和日志文件
    -   它支持添加覆盖文件系统 `file://` 文件
-   **快速访问**数字 : `@codingame/monaco-vscode-quickaccess-service-override`
    -   启用编辑器中的快速访问菜单( 按 F1 或 ctrl+ shift+p)
-   **搜索**数字 : `@codingame/monaco-vscode-search-service-override`
    -   为命令调色板文件搜索(Ctrl+P)和搜索面板(Ctrl+Shift+F)提供工作空间搜索功能
    -   允许在工作空间内搜索文件和文本内容

然而,大多数服务被分离成不同的模块,因此可以根据需要导入. 服务列表 [对应的维基页面](https://github.com/CodinGame/monaco-vscode-api/wiki/List-of-service-overrides)。 。 。 .

### 默认 vscode 扩展

VSCode使用一串默认扩展. 大部分用于装入默认语言和语法(参见: [https://github.com/microsoft/vscode/tree/main/extensions (中文(简体) )](https://github.com/microsoft/vscode/tree/main/extensions)) (中文(简体) ).

这个库将它们捆绑起来,并作为单独的包出版,这样可以使用你想要的包. 要使用扩展名,只需安装相应的软件包并在文件开头导入:

```typescript
import '@codingame/monaco-vscode-javascript-default-extension'
import '@codingame/monaco-vscode-json-default-extension'
...
```

以下是默认 VSCode 主题扩展的用法示例 :

```typescript
// importing default VSCode theme extension
import '@codingame/monaco-vscode-theme-defaults-default-extension'

// default monaco-editor imports
import * as monaco from 'monaco-editor'
import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker'

// utilities to override Monaco services
import { initialize } from '@codingame/monaco-vscode-api'
import getThemeServiceOverride from '@codingame/monaco-vscode-theme-service-override'

window.MonacoEnvironment = {
  getWorker: function (_moduleId, _label) {
    return new editorWorker()
  }
}

// overriding Monaco service with VSCode
await initialize({
  ...getThemeServiceOverride()
})

// creating an editor with VSCode theme
monaco.editor.create(document.getElementById('editor')!, {
  value: 'Editor with VSCode Theme Support'
})
```

见 [端口默认扩展的完整列表](https://www.npmjs.com/search?q=%40codingame%2Fmonaco-vscode-*-default-extension)

### 正在装入 v6 文件

VSCode 扩展被捆绑为 v6 文件 . 这个库会发布一个滚出插件(vite-compatible),允许加载 v6 文件.

-   滚动/视频配置 :

```typescript
import vsixPlugin from '@codingame/monaco-vscode-rollup-vsix-plugin'
...
plugins: [
  ...,
  vsixPlugin()
]
```

-   代码 :

```typescript
import './extension.vsix'
```

### 本地化

这个库还提供了将 vscode 和扩展以所支持的语言本地化的可能性. 为此,首先导入以下软件包之一:

-   `@codingame/monaco-vscode-language-pack-cs`
-   `@codingame/monaco-vscode-language-pack-de`
-   `@codingame/monaco-vscode-language-pack-es`
-   `@codingame/monaco-vscode-language-pack-fr`
-   `@codingame/monaco-vscode-language-pack-it`
-   `@codingame/monaco-vscode-language-pack-ja`
-   `@codingame/monaco-vscode-language-pack-ko`
-   `@codingame/monaco-vscode-language-pack-pl`
-   `@codingame/monaco-vscode-language-pack-pt-br`
-   `@codingame/monaco-vscode-language-pack-qps-ploc`
-   `@codingame/monaco-vscode-language-pack-ru`
-   `@codingame/monaco-vscode-language-pack-tr`
-   `@codingame/monaco-vscode-language-pack-zh-hans`
-   `@codingame/monaco-vscode-language-pack-zh-hant`

QQ 语言包应该导入并加载, 然后再装入此库中的其他内容 。 否则,一些翻译会丢失,一个错误会在控制台上显示. ⚠️

## 模型创建

官员 `monaco-editor` 软件包提供了创建模型的功能: `monaco.editor.createModel`。 。 。 .

这种方法创造了一个无法被任何VSCode服务所找到或使用的独立模型.

建议采用的方法是: `createModelReference` 方法取而代之(在正式的monaco-editor api上添加),它返回一个模型的引用.

它有一些职业:

-   模型引用可以被 VSCode 服务使用, 例如允许在文件之间连接( ctrl+ 点击)
-   返回的模型被绑定在一个文件系统文件上,您可以访问允许控制文件生命周期的方法(保存文件,访问脏态.)
-   可以在同一文件中多次调用该方法以获得多处引用. 在没有参考文献时处理模型

要工作,它需要文件存在于虚拟文件系统中. 可以通过下列方式实现:

-   使用 `registerFileSystemOverlay` 从文件服务覆盖, 当不再需要时可以清理( 建议)
-   使用 `createModelReference` 函数,在创建模型之前将文件内容写入虚拟文件系统

在此之前:

```typescript
import * as monaco from 'monaco-editor'
const model = monaco.editor.createModel(...)
const editor = monaco.editor.create({ model, ... })

...

model.dispose()
editor.dispose()

```

之后:

```typescript
import * as monaco from 'monaco-editor'
import { RegisteredFileSystemProvider, RegisteredMemoryFile, registerFileSystemOverlay } from '@codingame/monaco-vscode-files-service-override'

const fileUri = monaco.Uri.file(<file uri>);

const fileSystemProvider = new RegisteredFileSystemProvider(false)
fileSystemProvider.registerFile(new RegisteredMemoryFile(fileUri, <file content>))
const overlayDisposable = registerFileSystemOverlay(1, fileSystemProvider)

const modelRef = await monaco.editor.createModelReference(fileUri)

const editor = monaco.editor.create({ model: modelRef.object.textEditorModel })

...

await modelRef.object.save()

...

modelRef.dispose()
editor.dispose()
overlayDisposable.dispose()

```

`createModelReference` 返回对模型的引用。 值是从内存文件系统中获取的 . 然后可以处理参考文献,只有在没有剩余参考文献的情况下才能处理该模型.

## VSCode api 使用量

要直接使用代码中的 VSCode api, 您需要导入 `vscode/localExtensionHost` 等待服务初始化.

然后,您就可以像VSCode扩展名一样导入:

```typescript
import * as vscode from 'vscode'
import 'vscode/localExtensionHost'

const range = new vscode.Range(...)
vscode.languages.registerCompletionItemProvider(...)
```

您也可从其清单中注册新的扩展:

```typescript
import { registerExtension, initialize, ExtensionHostKind } from '@codingame/monaco-vscode-api/extensions'

await initialize()

const { registerFileUrl, getApi } = registerExtension({
  name: 'my-extension',
  publisher: 'someone',
  version: '1.0.0',
  engines: {
      vscode: '*'
  },
  contributes: {
  }
}, ExtensionHostKind.LocalProcess)

registerFileUrl('/file-extension-path.json', new URL('./file-real-path.json', import.meta.url).toString())

const vscode = await getApi()

vscode.languages.registerCompletionItemProvider(...)

```

### 演示

试试看 [https://monaco-vscode-api.netlify.app/ 页面存档备份,存于互联网档案馆](https://monaco-vscode-api.netlify.app/)

有一个演示演示了服务覆盖功能. 它包括:

-   语文
-   VSCode 主题
-   文本语法( 需要 VSCode 主题)
-   通知/联络
-   模式/编辑服务
-   配置服务, 配备用户配置编辑器
-   密钥绑定服务, 有用户密钥绑定编辑器
-   调试器
-   远程代理
-   还要多得多

从 CLI 运行 :

```bash
# build monaco-vscode-api (the demo use it as a local dependency)
npm ci
npm run build
# start demo
cd demo
npm ci
npm start
# OR: for vite debug output
npm run start:debug
```

对于调试特性, 也运行 :

```bash
npm run start:debugServer
```

QQ Building monaco-vscode-api 只在 Linux 或 Mac 上支持 。 你用Windows,看看这个 [WSL 维基月球](https://learn.microsoft.com/windows/wsl/install) ⚠️

#### 远程代理

见 [VSCode 服务器](https://github.com/CodinGame/monaco-vscode-api/wiki/How-to-install-and-use-VSCode-server-with-monaco%E2%80%90vscode%E2%80%90api) 维基页面.

## 阴影多姆( QQ β QQ)

图书馆支持"阴影度".

QQ VSCode本身不支持"阴影多姆",有多个部件需要被补丁才能工作.

使用它有多种好处:

-   您的自定义全局样式不会影响 VSCode 工作台样式( 例如, 如果您确实覆盖了默认) [框大小](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing)(中文(简体) )
-   VSCode风格不会影响你应用的其他部分
-   您的页面头不会被污染 从VSCODE的十几个cs文件

### 怎样用

如果提供的容器元素是阴影多姆元素的子,样式会同时被注入主页和阴影根. 就是这样.

### 先决条件

为了也能将静态的 Cs 文件也装入阴影多姆. 您的捆绑器配置需要被修改, 以便导入的 css 文件不会在页面头加载内容, 而只是返回文件内容为默认( 要么作为字符串 要么作为 `CSSStyleSheet`) (中文(简体) ). 可以通过大多数捆绑器和一些配置来实现.

请注意,捆绑者仍应解决 Cs 文件中引用的资产,所以你不能仅仅使用 `raw` 装载器,或 `assets/source` 网络包模块类型.

#### 网络软件包

在配置中添加此规则 :

```typescript
{
  test: /node_modules\/(@codingame\/monaco-vscode|vscode|monaco-editor).*\.css$/,
  use: [
    {
      loader: 'css-loader',
      options: {
        esModule: false,
        exportType: 'css-style-sheet', // or 'string', both are working
        url: true,
        import: true
      }
    }
  ]
}
```

您还应确保没有其他装载机干扰, 无论是使用 `oneOf` 或者把这些文件 排除于其他 css 加载器.

#### 维特

在配置中添加此插件 :

```typescript
{
  name: 'load-vscode-css-as-string',
  enforce: 'pre',
  async resolveId(source, importer, options) {
    const resolved = (await this.resolve(source, importer, options))!
    if (
      resolved.id.match(
        /node_modules\/(@codingame\/monaco-vscode|vscode|monaco-editor).*\.css$/
      )
    ) {
      return {
        ...resolved,
        id: resolved.id + '?inline'
      }
    }
    return undefined
  }
}
```

## 沙盒模式 (QQ) β QQ)

与VSCode的一个问题就是它的设计只有一次被初始化. 因此初始化选项(workbench 选项,远程服务器权限. )无法更新/再加载. 也不可能"卸载"服务.

要仍然能够做到这一点,一种可能性是将所有VSCode代码运行在一个iframe内部,而不是在主页中. 但VSCode会只在iframe中渲染,不会很好地融入页面.

为了更好的整合,也可以在iframe中运行代码,但使代码与主页多姆交互.

此库支持该模式 。 要做到这一点,你应当

-   拥有一个二级 html 切入点,可以初始化服务
-   在 iframe 中装入二级 html
-   iframe, 设置 `window.vscodeWindow` 到母窗口时,也可以在窗口中安装容器初始化服务
-   不从顶端窗口导入任何 monaco- vscode- library, 但是您可以在 iframe 窗口上声明函数, 以使对象到顶端窗口

"卸下"工作台,你应该:

-   从上方框去掉 iframe 元素
-   删除或清空工作台容器
-   清除 VSCode 在页面头注入的元素 : `document.querySelectorAll('[data-vscode]').forEach((el) => el.remove())`

⚠️ `window.vscodeWindow` 应在装入任何 VSCode 代码之前设置

注意: 可以和阴影多姆结合使用

在演示中显示,通过添加 `?sandbox` 向演示 url 查询参数

## 解决问题

如果有什么不起作用,请检查一下 [解决问题](https://github.com/CodinGame/monaco-vscode-api/wiki/Troubleshooting) 维基页面.

## 历史

这个项目主要是为了执行 [莫纳科语客户端](https://github.com/TypeFox/monaco-languageclient) 更坚固,更可维护.

摩纳哥语客户端用途 [vscode-语言客户端](https://www.npmjs.com/package/vscode-languageclient) 用于在VSCode扩展内运行。 VSCode 扩展通过一个 [API 密码](https://www.npmjs.com/package/@types/vscode) 他们可以输入他们的代码.

[VSCode api (英语)](https://code.visualstudio.com/api/references/vscode-api) 输出 :

-   与 IDE 互动的一些功能( Name[语言特征注册](https://code.visualstudio.com/api/references/vscode-api#languages), (中文(简体) ), [命令执行](https://code.visualstudio.com/api/references/vscode-api#commands). ) (中文(简体) )
-   很多公用类( Range, 位置. )

最初的执行情况 [莫纳科语客户端](https://github.com/TypeFox/monaco-languageclient) 使用假 VSCode api 执行。 Vscode- 语言客户端被黑入, 因此 VSCode <- > protocol 对象转换器主要被绕过, 所以假 VSCode api 正在接收 [语言服务器协议](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/) 对象。 然后用自定义变压器将对象转换成 [摩纳哥](https://www.npmjs.com/package/monaco-editor) 对象与 monaco api 通信.

这种办法有一些缺点:

-   有很多代码可以将 LSP 对象转换成摩纳哥对象
-   很难跟踪 VSCode 和语言服务器协议的更新
-   它的表现和VSCode不完全一样

通过这个库,可以直接将vscode语言客户端插到monaco上方,monaco语言客户端仍然通过:

-   正在将一些 tweaks 添加到 VSCode 语言库中( 删除不支持的特性... )
-   提供一些如何构建应用程序的例子
-   添加一些工具( 可处理收集)

## 常见问题

### @codingame/monaco-vscode-api 是什么？

VSCode 公共 API 插入了 monaco 编辑器

### 如何安装 @codingame/monaco-vscode-api？

在项目目录运行 npm install @codingame/monaco-vscode-api，或使用 pnpm add / yarn add / bun add。

### @codingame/monaco-vscode-api 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @codingame/monaco-vscode-api 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @codingame/monaco-vscode-api 可以商用吗？

@codingame/monaco-vscode-api 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @codingame/monaco-vscode-api 的下载量有多少？

根据 npm 官方下载统计，@codingame/monaco-vscode-api 在 2026/10/10 – 2026/11/08 这 30 天内被下载 688,305 次，日均约 22,944 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @codingame/monaco-vscode-api 还在维护吗？

最新版本 39\.0\.4 发布于 2026/11/09（今天）；至今共发布 487 个版本，其中过去 12 个月发布了 119 个；首次发布于 2022/06/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。