CQL 教程 - VS Code 插件安装

28.1插件简介

CQL-Lang for VS Code 是 CQL 中文编程语言的官方 VS Code 内核插件，以 VSIX 格式分发，适用于 VS Code 桌面版与 VS Code 内核（Code OSS / VSCodium 等）。

项目	说明
插件名称	`cql-lang-vscode`
当前版本	`1.37.0`
文件格式	`.vsix`（VS Code 扩展包）
项目地址	https://github.com/CQFISH-YJY/cql-lang-vs_code
核心能力	`.cql` 语法高亮、关键字与内置函数补全、代码片段提示

提示：插件与 cql 命令行工具是相互独立的。命令行工具负责运行与编译，插件负责编辑体验，两者配合使用效果最佳。

28.2下载插件

打开项目发布页的 Releases 下载区，下载最新版 VSIX 文件，或直接点击下面的官方直链下载：

下载地址

https://github.com/CQFISH-YJY/cql-lang-vs_code/releases/download/visx/cql-lang-vscode-1.37.0.vsix

下载完成后，你会得到一个 cql-lang-vscode-1.37.0.vsix 文件。将它放到一个容易找到的目录（例如「下载」文件夹），接下来任选一种方式安装。

注意：请从官方 Releases 页面下载，不要使用来路不明的安装包；文件版本号与发布页保持一致，避免下载旧版本。

28.3方式一：命令行安装

最快捷的方式。打开系统命令行（Windows 使用 PowerShell 或 cmd，macOS / Linux 使用终端），使用 VS Code 自带的 code 命令安装。

第一步：确认 code 命令可用

bash

code --version

如果提示 code 不是内部或外部命令，请在 VS Code 中按 Ctrl+Shift+P，输入 Shell Command: Install 'code' command in PATH 并回车执行，然后重新打开终端。

第二步：执行安装命令

将命令中的路径替换为你实际的 .vsix 文件位置：

bash

code --install-extension C:\Users\你的用户名\Downloads\cql-lang-vscode-1.37.0.vsix

也可先进入文件所在目录再安装：

bash

cd Downloads
code --install-extension cql-lang-vscode-1.37.0.vsix

看到类似 Installing extensions... 与 Extension 'cql-lang-vscode' v1.37.0 was successfully installed! 的输出即表示安装成功。

提示：使用 VS Code 内核（如 VSCodium）时，命令可能为 codium --install-extension ...，其余步骤完全一致。

28.4方式二：界面安装

不习惯命令行的朋友，可以用 VS Code 图形界面完成安装，无需任何命令。

第一步：打开扩展面板

点击左侧活动栏的扩展图标（快捷键 Ctrl+Shift+X）。

第二步：选择「从 VSIX 安装」

在扩展面板右上角点击 ... 更多菜单，选择「Install from VSIX...」（从 VSIX 安装）。

第三步：选择文件并确认

在弹出的文件选择窗口中，定位并选中 cql-lang-vscode-1.37.0.vsix，点击打开。等待片刻，右下角会提示安装完成。

注意：部分网络环境或企业版 VS Code 会限制「从 VSIX 安装」，若菜单项为灰色，请改用命令行方式安装。

28.5方式三：拖拽安装

最简单直观的方式：在系统文件管理器中选中 .vsix 文件，直接拖拽到 VS Code 编辑器窗口内（拖到代码编辑区即可），松开鼠标后 VS Code 会自动弹出安装确认，点击「Install」完成安装。

注意：拖拽安装要求 VS Code 为较新版本；若拖入后无反应，请使用方式一或方式二安装。

28.6验证安装

安装完成后，按下面的步骤验证插件是否生效。

检查扩展列表

打开扩展面板（Ctrl+Shift+X），在搜索框输入 cql-lang，应能看到已安装的 cql-lang-vscode，且状态为「已启用」。

创建 .cql 文件

新建一个 hello.cql 文件，输入下面的中文代码：

cql

打印("你好，VS Code！")

如果关键字 打印 被高亮为橙色、字符串显示为青色，且输入 打印 时出现补全提示，说明插件已正常工作。

提示：插件会自动识别 .cql 扩展名；若文件仍未高亮，点击窗口右下角语言模式（当前显示为「纯文本」），选择 CQL 即可。

28.7使用与配置

插件安装后即可使用，无需额外配置。以下可选配置能让体验更顺手。

在终端中运行 .cql

确保已安装 cql-lang（pip install cql-lang），即可在 VS Code 内置终端中直接运行：

bash

cql run hello.cql

设置文件关联（可选）

在 settings.json 中添加以下配置，将 .cql 始终按 CQL 语言处理：

json

{
  "files.associations": {
    "*.cql": "cql"
  }
}

打开方式：Ctrl+Shift+P 输入 Preferences: Open Settings (JSON)。

注意：补全与高亮属于编辑器体验，不包含运行功能；编译、运行与转译仍由 cql 命令行工具完成。

28.8卸载插件

不再需要时，可通过命令行或界面卸载。

命令行卸载

bash

code --uninstall-extension cql-lang-vscode

界面卸载

扩展面板搜索 cql-lang，点击已安装扩展右下角的设置图标，选择「卸载」，确认后重启 VS Code 即可。