VSCode插件教程：LSP协议初始化参数详解

LSP 协议初始化参数详解：从握手到配置

上一节我们完成了 LSP 代码补全的基础实现，现在可以着手搭建一个真正可运行的 LSP 系统。但在进入实战前，有必要把初始化阶段的细节彻底理清。

第4节已经介绍了 LSP 握手流程。具体而言，在 connection 的 onInitialize 回调中，服务端能读取客户端传来的初始化参数——例如客户端支持哪些能力。实现代码大致如下：

connection.onInitialize((params: InitializeParams) => {
    let capabilities = params.capabilities;
    return {
        capabilities: {
            textDocumentSync: documents.syncKind,
            // 告诉客户端，服务端支持代码补全
            completionProvider: {
                resolveProvider: true
            }
        }
    };
});

下图概括了 LSP 初始化参数的整体结构：

接下来逐条拆解这些参数的定义：

interface InitializeParams {
    /** 启动服务端的父进程 ID。
     *  若服务端非由其他进程启动，则为 null。
     *  父进程意外终止时，服务端应自行退出（参见退出通知）。
     */
    processId: number | null;

    /** 工作区根路径。
     *  若未打开任何文件夹，则为 null。
     *  @deprecated 建议改用 rootUri。
     */
    rootPath?: string | null;

    /** 工作区根 URI。
     *  若未打开任何文件夹，则为 null。
     *  若同时提供 rootPath 和 rootUri，rootUri 优先。
     */
    rootUri: DocumentUri | null;

    /** 用户自定义的初始化选项。 */
    initializationOptions?: any;

    /** 客户端（编辑器或工具）所具备的能力声明。 */
    capabilities: ClientCapabilities;

    /** 初始跟踪日志级别。若省略，默认关闭跟踪（'off'）。 */
    trace?: 'off' | 'messages' | 'verbose';

    /** 服务端启动时，客户端已配置的工作区文件夹列表。
     *  仅在客户端支持工作区文件夹功能时可用。
     *  若客户端支持但未配置任何文件夹，则为 null。
     *  @since 3.6.0
     */
    workspaceFolders?: WorkspaceFolder[] | null;
}

将以上参数归类后，可整理成下图所示的三类信息：

它们主要涵盖三大维度：

第一类是与运行环境相关的信息，例如进程 ID、工作区路径与 URI。第二类是客户端的支持能力清单。第三类则包括跟踪开关、用户自定义初始化选项等辅助配置。

需要特别留意的细节：路径相关字段仅在 VSCode 确实打开了一个目录时才可用。举例来说，若我打开的目录是 /Users/ziyingliuziying/working/gitlab/cafmode/server，那么 rootPath 返回的正是这一字符串，而 rootUri 会以 file:///Users/ziyingliuziying/working/gitlab/cafmode/server 的形式呈现。workspaceFolders 则是一个包含 WorkspaceFolder 对象的数组，每个对象包含 name 和 uri 两个属性。以同一目录为例，name 为 server，uri 同样为 file:///Users/ziyingliuziying/working/gitlab/cafmode/server。