一、项目简介：什么是 Monaco Editor
Monaco Editor 是微软开源的、基于浏览器的全功能代码编辑器内核，也就是驱动 Visual Studio Code 桌面版的那同一个编辑器。它由 VS Code 的核心代码直接抽取而来，并在外层包裹了一层适配浏览器运行环境的 shim（垫片），因此你在 VS Code 里熟悉的语法高亮、智能补全、多光标编辑、命令面板、大纲视图、面包屑、括号配对等能力，几乎都能在网页里原样复现。官方仓库位于 microsoft/monaco-editor，采用 MIT 许可证，可自由用于商业与个人项目，无需开源衍生作品。它在 GitHub 上长期保持活跃维护，微软团队持续跟随 VS Code 的内核迭代同步更新。
许多知名在线产品都把 Monaco 作为内嵌编辑器，例如各类在线 IDE、在线 SQL 编辑器、低代码平台的脚本编辑框、博客的 Markdown 与代码片段编辑器、在线表单的公式编辑框等。它天生就是为"嵌入到你自己的 Web 应用"而设计的库，而不是一个独立成品。官方提供了一个可交互的 Playground 在线演示，在上面可以即改即看、切换不同版本、生成最小复现用例，是学习用法、反馈 Bug 的最佳入口。
它支持语法高亮、智能感知、代码折叠、多光标与选区、查找替换、括号自动闭合、自动缩进、缩略图（minimap）、分割编辑器并排比较、命令行式的快速命令面板、自定义主题与自定义语言（通过 Monarch 语法规则）等特性。由于与 VS Code 同源，编辑器的按键习惯、交互细节几乎与桌面版一致，开发者几乎零学习成本就能上手。对中文使用者而言，界面语言、字体渲染、IME 中文输入法的兼容性也都经过长期验证。
在动手集成之前，建议先理解五个核心概念。Model（模型）是一切的中心，代表一份打开的文件，它持有文本内容、判定语言类型、追踪编辑历史；模型不一定对应真实磁盘文件，也可以是内存里的虚拟文件。URI 是每个模型的唯一标识，两个模型不能共用同一个 URI，推荐用 file:/// 作为虚拟文件系统的根路径来模拟用户正在编辑的真实文件；若创建模型时不指定 URI，它会被分配为 inmemory://model/1，数字随模型增多而递增。Editor（编辑器）是模型对外可见的视图，负责挂载到 DOM、展示模型、管理视图状态、执行动作与命令。Provider（提供者）对外提供补全、悬停信息等智能特性，它映射到 语言服务器协议（LSP） 的能力，且部分特性依赖文件 URI（例如 TypeScript 解析 import、JSON 根据模型选择对应 schema），因此给模型起一个规范的 URI 很重要。Disposable（可释放对象）：许多 Monaco 对象都实现了 .dispose() 方法用于资源回收，例如 model.dispose() 会注销模型并释放 URI，编辑器也应 dispose 以移除模型监听器、避免内存泄漏。
二、环境准备与前置依赖
Monaco 是一个纯前端库，部署本质上就是"把它打包或加载进你的网页"。在开始之前，请准备好以下环境。
- Node.js 16 及以上版本（推荐当前 LTS），并自带 npm，或改用 pnpm/yarn；
- 一个现代桌面浏览器（Chrome、Edge、Firefox、Safari 最新版）；官方明确表示不支持移动浏览器与移动 Web 框架内嵌；
- 如果你打算用打包器，需要熟悉 webpack、Vite 或 Rollup 之一；
- 一份可对外访问的静态站点或前端工程。特别注意：HTML5 不允许通过
file://协议页面创建 Web Worker，因此本地预览必须用http://或https://起一个本地服务器，而不是直接双击 HTML 文件。
先确认 Node 与 npm 可用：
node -v
npm -v然后新建工程目录并安装：
mkdir my-monaco-demo && cd my-monaco-demo
npm init -y
npm install monaco-editor如果 npm install monaco-editor 较慢或失败，可以切换国内 npm 镜像源：npm config set registry https://registry.npmmirror.com，再重新安装。安装时若报 Node 版本不满足 engines 要求，请升级到 LTS。验证安装成功的最简单方式是在工程里 node -e "console.log(require('monaco-editor/package.json').version)" 打印出版本号。
安装完成后，node_modules/monaco-editor 目录里会得到两类关键产物：/esm 目录是 ESM 版本的编辑器，可直接被 webpack、Vite 消费；monaco.d.ts 是类型声明文件，描述了对外稳定的公共 API——这也是真正会随版本号演进的部分，其余内部实现都可能在任意版本变动。需要特别提醒：仓库同时附带了一份 AMD 构建用于向后兼容，但 AMD 支持已被标记为废弃，未来版本会移除，新工程应优先使用 ESM 方式。
三、部署方式一：npm + 打包器（ESM，推荐）
这是官方推荐、也是生产环境最稳妥的集成方式。以 webpack 为例，完整说明见仓库文档 Integrate the ESM version 以及 samples 目录下的完整示例工程。
安装依赖：
npm install monaco-editor
npm install --save-dev webpack webpack-cli webpack-dev-server在入口 JS 中通过 ESM 引入并创建编辑器：
import * as monaco from 'monaco-editor';
monaco.editor.create(document.getElementById('container'), {
value: 'function hello() {\n\talert("Hello world!");\n}',
language: 'javascript',
theme: 'vs-dark',
automaticLayout: true
});如果你只需要核心编辑能力，而不需要内置的 TypeScript、HTML、CSS、JSON 等完整语言服务，可以手动按需引入以减小产物体积。此时需要自己配置 Web Worker：
import * as monaco from 'monaco-editor';
import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';
self.MonacoEnvironment = {
getWorker: function (workerId, label) {
return new editorWorker();
}
};
monaco.editor.create(document.getElementById('container'), {
value: '// 这里是你的代码',
language: 'plaintext'
});编辑器创建时常用的配置项包括 value（初始文本）、language（语言标识）、theme（内置 vs、vs-dark、hc-black 三套主题）、wordWrap（自动换行）、readOnly（只读）、minimap.enabled（缩略图）、fontSize 与 tabSize 等。代码层面常见操作还有 monaco.editor.createModel 显式建模型、model.setValue()/getValue() 读写文本、monaco.languages.registerCompletionItemProvider 注册自定义补全。需要注意，多个编辑器共享同一份文本时应复用同一个 Model，而不是各自 create 一份相同内容，否则会浪费内存且无法保持一致。
若使用 Vite 且希望省去手写 worker 的样板代码，社区维护的 monaco-editor-vite 之类封装可以一键注入 worker；但直接按上面 ?worker 写法手动注册同样可靠，且不引入额外依赖。官方 Playground 内置了 webpack、Vite、AMD 等多种模板，选择后可一键导出最小可运行工程。
四、部署方式二：script 标签 / CDN（快速试验）
如果你只是想快速试验、不想引入打包器，可以直接用 script 标签加载。官方已不推荐在生产环境长期依赖 AMD，但用于 Demo 仍然可行：
<div id="container" style="width:800px;height:600px;border:1px solid #ccc"></div>
<script src="https://cdn.jsdelivr.net/npm/monaco-editor@0.55.1/min/vs/loader.js"></script>
<script>
require.config({ paths: { vs: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.55.1/min/vs' } });
require(['vs/editor/editor.main'], function () {
monaco.editor.create(document.getElementById('container'), {
value: 'print("hello world")',
language: 'python',
theme: 'vs'
});
});
</script>把这段 HTML 放到任意静态目录，用 npx serve . 或 python3 -m http.server 8080 起本地服务后访问 http://localhost:8080 即可。这种方式无需任何构建步骤，适合做概念验证。若要完全本地化部署 CDN 资源，只需把 npm pack monaco-editor 解开后的 min/vs 整个目录下载到你自己的服务器，再把 require.config 里的 paths.vs 指向本地路径（例如 /vendor/vs），即可实现离线、内网可用。
这种 script 标签方案的好处是零构建、易部署到任意静态托管；缺点是 AMD 加载机制已废弃、按需裁剪困难、首屏需要额外加载 loader.js，因此仅建议在原型验证、内网工具、技术 Demo 中使用。正式产品请回到 ESM 打包方案，以便走 CI/CD、做代码分包与缓存策略。
五、部署方式三：从源码构建与本地开发
当你需要二次开发、调试 Monaco 本身，或想向社区贡献代码时，可以直接从源码运行。按照仓库 CONTRIBUTING 的说明操作：
git clone https://github.com/microsoft/monaco-editor.git
cd monaco-editor
npm install
npm run watch启动完成后，打开 test/samples/index.html（通过本地服务器访问）即可看到大量官方样例。调试核心编辑器用 npm run watch，调试各语言服务（languages）则使用对应的 debug 任务。官方文档里提供了两套调试场景的演示，分别对应核心编辑功能与语言服务：
源码目录结构上，website 目录是 Playground 与文档站点本身，samples 是各打包器集成示例，test/samples 是运行时调试样例。提交代码前请阅读 CONTRIBUTING 中的代码规范与测试要求，确保通过 npm run test。由于 Monaco 与 VS Code 同源，部分改动需要同时考虑在 VS Code 侧的兼容性。
多语言本地化方面，如果希望编辑器的界面提示以德语等特定语言显示，需要在主 monaco 脚本之前先加载对应的 nls 文件。例如加载德语：
<script src="path/to/monaco-editor/esm/nls.messages.de.js"></script>可用语言列表请查看 ESM 目录下的 nls.messages.*.js 文件。关于无障碍（a11y），官方还提供了一份 Integrator 无障碍指南，面向屏幕阅读器场景务必对照配置。如果你想为一门新的编程语言编写高亮规则，可以在 Monarch Playground 里在线调试 Monarch 令牌化器。
六、常见问题与 FAQ（含报错解决）
Q1：控制台报 "Could not create web worker" 怎么办？
A：这是因为页面通过 file:// 协议直接打开，HTML5 出于安全限制不允许这种页面创建 Web Worker。解决方法就是改用 http:// 或 https:// 协议，通过本地静态服务器（如 npx serve、python -m http.server）访问页面即可。
Q2：我写的 VS Code 扩展能直接在浏览器里的 Monaco 上跑吗？
A：不能。Monaco 是从 VS Code 源码裁剪出来的库，并不具备 VS Code 完整的扩展宿主环境。唯一的例外是：如果你的扩展完全基于 LSP，且语言服务器本身是用 JavaScript 编写的，才有可能在浏览器端运行。
Q3：为什么有这么多 Web Worker？需要担心吗？
A：语言服务会把补全、语法分析等重计算放到 UI 线程之外的 Web Worker 里执行，资源开销极小，只要它能正常启动即可。唯一需要处理的是跨域部署场景下 worker 脚本的路径配置问题，确保 worker 脚本与主页面同源或正确配置了 CORS。
Q4：Monaco 为什么不直接支持 TextMate 语法？
A：Monaco 自带的是 Monarch 令牌化引擎。如需 TextMate 语法，可参考 bolinfest/monaco-tm，它把 monaco-editor、vscode-oniguruma 与 vscode-textmate 组合起来实现 TM 语法支持。
Q5：VS Code 版本号和 Monaco 版本号有对应关系吗？
A：没有。Monaco 是一个独立的库，它的版本号直接反映自身源码发布节奏，与 VS Code 的版本号无关，升级时请以 npm 页面上的最新稳定版为准。
Q6：编辑器在容器里高度/宽度不对、显示不全怎么办？
A：这是因为 Monaco 依赖 DOM 元素尺寸，容器 resize 时不会自动重排。创建时加上 automaticLayout: true，或在窗口缩放时手动调用 editor.layout() 即可解决。
Q7：打包后产物体积太大怎么办？
A：默认引入 monaco-editor 会带上所有内置语言服务。若你只需要一两种语言，应改为手动从 monaco-editor/esm/vs/editor/editor.api 引入核心，再按需引入具体语言贡献与对应 worker，并在 getWorker 中只返回需要的 worker，可显著减小产物体积。
Q8：能否在 vscode.dev / github.dev 这类网页版里使用？
A：Monaco 本身就是浏览器端编辑器，完全可以；而 vscode.dev 是更上层的完整 VS Code 网页版产品，二者定位不同。要在浏览器里写代码，直接用 Monaco 嵌进自己页面即可，无需依赖 vscode.dev。
Q9：如何监听用户输入、获取内容变化？
A：通过 model.onDidChangeContent(event => { ... }) 监听文本变更，返回的是一个 Disposable，组件卸载时记得调用其 .dispose()。若要在失去焦点或保存时取文本，用 editor.getValue() 即可。
七、总结与相关资源
Monaco Editor 是目前浏览器端最成熟、生态最完善的代码编辑器内核：想要快速验证就用 CDN script 方案，想要工程化生产就用 npm + webpack/Vite 的 ESM 方案，想要改源码或贡献则 clone 仓库跑 npm run watch。集成时牢记 Model、URI、Editor、Provider、Disposable 五个概念，记得在 http(s) 协议下运行、及时 dispose 释放资源，并给容器加上自动布局，就能避开绝大多数坑。
升级版本时建议先在 Playground 切换到目标版本验证既有代码是否兼容，因为 monaco.d.ts 之外的内部 API 可能在任意版本变动。生产部署完成后，可通过浏览器开发者工具的 Network 面板确认所有 worker 脚本都以 200 加载、Console 无报错，即代表部署成功。
从成本看，CDN 方案首屏最快但长期依赖外部网络；ESM 打包方案可控性最好、产物体积可裁剪，是中大型产品的首选；源码方案只在你要改编辑器本身时才需要。三者并不互斥，可以用 CDN 做快速验证，再平滑迁移到打包方案。
进一步学习可参考：官方 API 文档、仓库里的 monaco.d.ts 类型定义、samples 完整示例，以及在 StackOverflow 的 monaco-editor 标签下搜索既有问答。遇到问题请先在仓库 Issues 中检索，避免重复反馈。