Azure Data Studio 仓库中 monaco-editor-core 的发布流程全指南：从 monaco.d.ts 生成到 npm publish-平芜编程栈

数据库客户端
桌面应用
数据分析

【免费下载链接】azuredatastudio

Azure Data Studio is a data management and development tool with connectivity to popular cloud and on-premises databases. Azure Data Studio supports Windows, macOS, and Linux, with immediate capability to connect to Azure SQL and SQL Server. Browse the extension library for more database support options including MySQL, PostgreSQL, and MongoDB.

项目地址：https://gitcode.com/gh_mirrors/az/azuredatastudio

点击查看免费下载

本指南以仓库 build/monaco/README.md 为骨架，完整讲解 Azure Data Studio（基于 VS Code / Monaco 内核）中monaco-editor-core独立包的发布流程：如何自动生成monaco.d.ts、如何正确升级版本号、如何通过gulp editor-distro产出可供 npm 发布的发行目录，并最终执行npm publish。读者学完后，将能独立完成一次 monaco 编辑器核心的版本发布，并理解发行目录中 ESM 源码、类型声明、min 产物与 sourcemap 是如何被组装出来的。

一、发布前置理解：什么是 monaco-editor-core

在动手发布之前，需要先明确产物定位。monaco-editor-core是 Monaco Editor（即驱动 VS Code 及 Azure Data Studio 的代码编辑器）的核心编辑功能模块，它只包含编辑器内核，不捆绑各语言的语法支持。

在 build/monaco/README-npm.md 中对该模块有明确定位说明：该 npm 模块是monaco-editor这个完整包的构建基石；除非你在做特殊的事（例如编写一个可以独立发布、独立被消费的 Monaco 语言包），否则建议直接消费monaco-editor包，因为该包内含本模块并额外叠加了语言支持。

对应地，仓库内的 build/monaco/package.json 中声明了该包的元数据：

{ "name": "monaco-editor-core", "private": true, "version": "0.0.0", "description": "A browser based code editor", "author": "Microsoft Corporation", "license": "MIT", "typings": "./esm/vs/editor/editor.api.d.ts", "module": "./esm/vs/editor/editor.main.js" }

注意三个关键点：

version在源仓库中恒为占位符0.0.0，真正的版本号在发布流程第 2 步手动提升；
private: true是源码仓库中的标记，构建流程（final-editor-resources）会将其改写为false，使其可被发布；
module入口指向esm/vs/editor/editor.main.js，typings指向esm/vs/editor/editor.api.d.ts，两者都是构建阶段才生成的文件。

二、发布流程总览

原文档给出了一条精炼的四步发布路径，本文将其展开为可执行的完整流程：

生成 monaco.d.ts——运行gulp watch，类型声明文件在构建中自动产生；
提升版本号——修改build/monaco/package.json中的version；
生成 npm 发行内容——确认全部改动已提交并推送到远程后，运行gulp editor-distro（生成物中包含 HEAD 的 SHA，必须保证该提交在远程可用）；
发布——进入输出目录out-monaco-editor-core并执行npm publish。

下面逐节详解每一步的机制与注意事项。

三、第一步：生成 monaco.d.ts

3.1 自动化机制

原文档明确指出：monaco.d.ts现在已无需手动维护，在运行gulp watch时会自动生成。它对应的产物文件是仓库根目录下的 src/vs/monaco.d.ts，该文件由build/lib/monaco-api.js驱动生成。

其生成逻辑的核心在 build/monaco/monaco.d.ts.recipe：这是一份"配方"文件，通过#include(...)与#includeAll(...)指令，把分散在vs/各模块中的类型声明按命名空间组装成一份完整的声明文件。以monaco.editor命名空间为例，配方中可见：

declare namespace monaco.editor { #include(vs/editor/browser/widget/diffNavigator): IDiffNavigator #includeAll(vs/editor/standalone/browser/standaloneEditor;languages.Token=>Token): ... //compatibility: export type IReadOnlyModel = ITextModel; export type IModel = ITextModel; }

这份配方文件还声明了全局环境接口MonacoEnvironment（getWorker、getWorkerUrl、baseUrl、globalAPI等字段）以及monaco、monaco.editor、monaco.languages、monaco.worker四个顶层命名空间，文件末尾的//dtsv=3是配方版本标记。

3.2 生成失败时的守护

生成流程并非"静默"完成。在 build/lib/compilation.js 中可以看到，monaco.d.ts的生成是构建的硬性前置条件：若生成失败，构建会抛出monaco.d.ts generation error - Cannot continue错误直接终止；若生成结果与已提交文件不一致，会报出monaco.d.ts is no longer up to date. Please run gulp watch and commit the new file.的提示——即提醒开发者重新跑gulp watch并提交更新后的声明文件。

3.3 类型检查与 watch 任务

在 build/gulpfile.editor.js 中还定义了monaco-typecheck与monaco-typecheck-watch两个 gulp 任务，它们通过tsc -p ./src/tsconfig.monaco.json --noEmit对 monaco 独立编译环境做类型检查。其中 watch 版本（createTscCompileTask(true)传入-w参数）会持续监听文件变化并即时反馈error TSxxxx类型的编译错误。虽然根目录 gulpfile.js 的watch任务默认注释掉了monacoTypecheckWatchTask，但开发者按需开启即可在编辑期间获得 monaco 侧的类型守护。

四、第二步：提升版本号

发布版本号的位置是 build/monaco/package.json 中的version字段，当前为占位符0.0.0。发布者需要：

将version改为符合 semver 语义的目标版本（如0.34.0）；
将该改动随发布提交一起git commit并推送。

版本号会被gulp editor-distro的final-editor-resources阶段继承：构建流程读取该package.json，仅把private改写为false，其余字段（含版本号、入口、typings 指向）原样写入发行目录的package.json中，见 build/gulpfile.editor.js。因此版本号必须在构建前就确定好并提交，而不是等构建后再改。

五、第三步：运行 gulp editor-distro 生成 npm 发行内容

5.1 硬性前提：所有改动已提交并推送

原文档特别强调：必须确保所有更改已经提交并推送到远程，因为生成的发行文件中包含 HEAD 的 sha，而该 sha 需要能在远程仓库查到（发行目录内的version.txt会写入指向该提交的链接）。若在本地提交尚未推送时发布，生成的产物将携带一个"远程不存在"的提交引用，导致产物溯源信息失效。

5.2 editor-distro 任务的完整流水线

editor-distro定义在 build/gulpfile.editor.js，是一条由多阶段任务串联组成的流水线：

util.rimraf(清理 out-editor-src / out-editor-build / out-editor-esm / out-monaco-editor-core / out-editor / out-editor-min) ← 并行清理 ↓ extractEditorSrcTask ← 抽取独立编辑器源码 ↓ 并行 分支 A（AMD 发行版）: compileEditorAMDTask → optimizeEditorAMDTask → minifyEditorAMDTask 分支 B（ESM 发行版）: createESMSourcesAndResourcesTask → compileEditorESMTask → appendJSToESMImportsTask ↓ finalEditorResourcesTask ← 组装最终 npm 包

各阶段职责如下：

并行清理：一次性删除六个out-*中间目录，保证每次构建从干净状态开始；
extractEditorSrcTask：从整个 VS Code 源码中抽取 Monaco 独立编辑器所需的源码子集；
分支 A（AMD）：依次完成编译、优化与压缩，产出out-editor与out-editor-min；
分支 B（ESM）：先通过createESMSourcesAndResourcesTask把源码转换到out-monaco-editor-core/esm（见 build/gulpfile.editor.js，其中会忽略vs/loader.js等加载器文件），再用 tsc 编译为 ESM 模块，最后执行appendJSToESMImportsTask。

appendJSToESMImportsTask（build/gulpfile.editor.js）是一个值得注意的细节：它遍历out-monaco-editor-core/esm下所有.js文件，把形如import ... from 'xxx'与export * from 'xxx'的语句统一改写为带.js后缀的形式（import$1'$2.js'），从而保证 ESM 导入在浏览器与打包器中的合规性。

5.3 final-editor-resources：组装 npm 包的最后一步

最终发行目录out-monaco-editor-core的内容由finalEditorResourcesTask（build/gulpfile.editor.js）组装，它同时并行完成多路复制与改写：

产物	来源	处理方式
`LICENSE`、`ThirdPartyNotices.txt`	build/monaco/LICENSE、build/monaco/ThirdPartyNotices.txt	原样复制
`monaco.d.ts`	src/vs/monaco.d.ts	原样复制到包根目录
`esm/vs/editor/editor.api.d.ts`	`src/vs/monaco.d.ts`	经`toExternalDTS`改写为 ESM 兼容的外部声明
`package.json`	build/monaco/package.json	解析后把`private`置为`false`再写回
`version.txt`	build/monaco/version.txt	写入`monaco-editor-core: <仓库>/tree/<sha1>`形式的提交溯源
`README.md`	build/monaco/README-npm.md	重命名为`README.md`后复制
`dev/`	`out-editor/**`	AMD 版产物原样放入 dev 目录
`min/`	`out-editor-min/**`	过滤掉`.js.map`、`nls.metadata.json`、`bundleInfo.json`，并重写`sourceMappingURL`指向`min-maps`
`min-maps/`	`out-editor-min/**`中的`.js.map`	仅保留 sourcemap 文件

其中两个改写逻辑值得展开：

toExternalDTS（类型声明 ESM 化）定义在 build/gulpfile.editor.js：它把declare namespace monaco {这一全局命名空间写法剥离，将declare namespace monaco.xxx {改写为export namespace，并把declare let MonacoEnvironment重写为declare global { let MonacoEnvironment: Environment | undefined; }——这样生成出的editor.api.d.ts才能作为标准 ESM 模块的类型声明被 TypeScript 正确解析。

min 目录的 sourceMappingURL 重写见 build/gulpfile.editor.js：压缩后的 JS 中原本内联的 sourcemap 引用会被替换为相对min-maps目录的相对路径，例如//# sourceMappingURL=../min-maps/vs/editor/editor.main.js.map，从而保证线上调试时 sourcemap 可被正确加载。

5.4 验证发行包：monaco.webpack.config.js 与 esm.core.js

发行目录是否可用，可通过仓库自带的两个文件交叉验证：

build/monaco/esm.core.js 是 webpack 打包的入口示例，它import * as monaco from 'monaco-editor-core'，配置MonacoEnvironment.getWorkerUrl返回./editor.worker.bundle.js，并调用monaco.editor.create渲染一段 JavaScript 示例代码；
build/monaco/monaco.webpack.config.js 则通过alias把'monaco-editor-core'指向out-monaco-editor-core/esm/vs/editor/editor.main.js，并以core与editor.worker两个入口打出dist/core.bundle.js与dist/editor.worker.bundle.js。

也就是说，本地即使不真正发布到 npm，也可以借助这份 webpack 配置在仓库内对 ESM 发行产物做一次完整打包冒烟验证。

六、第四步：发布到 npm

发行目录就绪后，执行发布：

cd out-monaco-editor-core npm publish

发布前建议自行核查：

out-monaco-editor-core/package.json中version是否为目标版本、private是否为false；
根目录的monaco.d.ts与esm/vs/editor/editor.api.d.ts是否已生成；
version.txt中的提交 SHA 是否已在远程仓库可见；
若发布的是新的大版本，注意核对 build/monaco/package.json 中typings与module指向的文件确实存在于发行目录中。

需要说明的是，npm publish本身需要 npm 账号与对应包名的发布权限，这属于账号与 npm 侧的配置，不在仓库代码范围内。

七、常见问题与排查要点

monaco.d.ts未更新：构建报monaco.d.ts is no longer up to date时，重新运行gulp watch让声明文件自动重新生成，并提交变更（见 build/lib/compilation.js）。
ESM 导入缺.js后缀：appendJSToESMImportsTask会统一补全，若你在out-monaco-editor-core/esm中手工改动文件后重新构建，务必让该任务重新执行，否则可能产生浏览器无法解析的裸导入。
版本号丢失或仍为 0.0.0：检查是否在修改 build/monaco/package.json 的version之前就运行了editor-distro，版本号必须在构建前改好。
发行目录内容与预期不符：对照 5.3 节的产物清单逐项核对，特别是min目录的 sourcemap 引用与version.txt的提交信息。

八、结语

monaco-editor-core的发布流程虽然只有四步，但背后是仓库中一条完整、自动化的构建流水线：monaco.d.ts由gulp watch依据 build/monaco/monaco.d.ts.recipe 自动拼装，版本号在 build/monaco/package.json 中控制，gulp editor-distro负责把 AMD、ESM、min 与 sourcemap 各类产物组装进out-monaco-editor-core，最终由npm publish推向公共 registry。理解这条链路，不仅是发布维护者所需，也能帮助二次开发 Monaco 语言包、深度定制编辑器的开发者更清楚地知道每一份发行文件的来源与用途。