{"meta":{"title":"设置 CodeQL CLI","intro":"要开始使用 CodeQL CLI，您需要下载并设置 CLI，以便 CLI 能够访问创建和分析数据库所需的工具和库。","product":"安全性和代码质量","breadcrumbs":[{"href":"/zh/code-security","title":"安全性和代码质量"},{"href":"/zh/code-security/how-tos","title":"How-tos"},{"href":"/zh/code-security/how-tos/find-and-fix-code-vulnerabilities","title":"查找和修复代码漏洞"},{"href":"/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line","title":"从命令行进行扫描"},{"href":"/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli","title":"设置 CodeQL 命令行工具"}],"documentType":"article"},"body":"# 设置 CodeQL CLI\n\n要开始使用 CodeQL CLI，您需要下载并设置 CLI，以便 CLI 能够访问创建和分析数据库所需的工具和库。\n\n## 设置 CodeQL CLI\n\n若要运行 CodeQL 命令，需要设置 CodeQL CLI 该命令，以便它可以访问创建和分析数据库所需的工具、查询和库。\n\n```\n          CodeQL CLI 支持多种用例和目录结构。 本文逐步讲解适用于大多数用户和环境的简单设置。\n```\n\n如果打算使用 CodeQL CLI 安全研究或测试或参与查询，则可能需要更高级的设置。 有关详细信息，请参阅“[关于 CodeQL CLI](/zh/code-security/concepts/code-scanning/codeql/about-the-codeql-cli#getting-started)”。\n\n### 在您开始之前\n\n如果在 Apple Silicon（例如 Apple M1）上使用 macOS，请确保已安装 [Xcode 命令行开发人员工具](https://developer.apple.com/library/archive/technotes/tn2339/_index.html)和 [Rosetta 2](https://support.apple.com/en-us/HT211861)。\n\n> \\[!NOTE]\n> 目前 CodeQL CLI 与非 glibc Linux 发行版（如基于 muslc 的）Alpine Linux 不兼容。\n\n### 1.下载 CodeQL CLI tar 存档\n\nCodeQL CLI 下载包是一个 zip 存档，其中包含工具、脚本和特定于 CodeQL 的各种文件。 如果没有 GitHub Enterprise 许可证，那么下载此存档即表示你同意 [GitHub CodeQL 条款和条件](https://securitylab.github.com/tools/codeql/license)。\n\n应从 <https://github.com/github/codeql-action/releases> 下载 CodeQL 包。 该捆绑包中包含：\n\n* CodeQL CLI 产品\n* 来自 <https://github.com/github/codeql> 的查询和库的兼容版本\n* 捆绑包中包含的所有查询的预编译版本\n\n应该始终使用 CodeQL 捆绑包。 这样可以确保兼容性，并且比单独下载 CodeQL CLI 和检出 CodeQL 查询提供更好的性能。 如果只在一个特定平台上运行 CLI，请下载相应的 `codeql-bundle-PLATFORM.tar.zst` 文件。 此外，也可以下载包含所有受支持平台的 CLI 的 `codeql-bundle.tar.zst`。\n\n捆绑包还有 `tar.gz` 变体，这些变体与 `tar.zst` 变体相同，但使用效率较低的 gzip 算法进行压缩。 下载 `tar.gz` 变体的唯一原因是使用不支持 Zstandard 压缩算法的较旧解压缩工具。\n\n### 2. 提取 CodeQL CLI tar 存档\n\n将 CodeQL CLI tar 存档解压缩到所选目录。\n\n### 可选：在 CI 系统中设置 CodeQL CLI 以使其可用\n\n如果计划在 CI 系统中运行 CodeQLcode scanning 分析，请确保捆绑包的完整内容 CodeQL CLI 可供运行分析的每个 CI 服务器使用。\n\n例如，您可以：\n\n* 从中央内部位置复制捆绑包，并在每台服务器上提取它，或\n* 使用 REST API 直接从GitHub中下载组件，确保收到对查询的最新改进。 有关详细信息，请参阅“[发布和发布资产的 REST API 终结点](/zh/rest/releases)”。\n\n### 3. 启动 `codeql`\n\n提取后，可以通过多种方式运行 `codeql` 可执行文件来运行 CodeQL 进程：\n\n* 通过执行 `<extraction-root>/codeql/codeql`，其中 `<extraction-root>` 是要在其中提取 CodeQL CLI 包的文件夹。\n* 通过将 `<extraction-root>/codeql` 添加到 `PATH`，这样就可以像 `codeql` 一样运行可执行文件。\n\n此时，可以执行 CodeQL 命令。 有关 CodeQL CLI 命令的完整列表，请参阅“[CodeQL CLI 命令手册](/zh/code-security/codeql-cli/codeql-cli-manual)”。\n\n> \\[!NOTE]\n> 如果将`codeql`添加到你的`PATH`，CodeQL 可以访问Visual Studio Code以编译和运行查询。 有关配置 VS Code 以访问该 CodeQL CLI对象的详细信息，请参阅 [在 VS Code 扩展中管理 CodeQL CLI](/zh/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli)。\n\n## 测试CodeQL CLI配置\n\n提取 CodeQL CLI 捆绑包后，可以运行以下命令来验证 CLI 是否已正确配置为创建和分析数据库：\n\n* ```\n            如果 `codeql resolve packs` 在 `/<extraction root>/codeql` 上，则 `PATH`。\n  ```\n* 否则为 `/<extraction root>/codeql/codeql resolve packs`。\n\n如果成功，你应该会看到类似以下摘录的输出：\n\n```shell\nSearching directories specified by `--additional-packs`. All directories have equal priority.\n  Searching in:\n    No packs were found at this location.\nSearching directories specified by `--search-path`. Directories are searched in order.\nSearching the root of the CodeQL distribution.\n  Searching in:\n      <extraction root>\n    The following packs were found:\n      codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml\n      codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml\n      codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml\n      codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml\n      codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml\n      codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml\n...\n```\n\n为简洁起见，结果已截断。 实际结果会更长且更详细。\n\n你应该检查输出是否包含预期的语言，以及 qlpack 文件的目录位置是否正确。 位置应位于提取出的 CodeQL CLI 捆绑包内，如之前的示例 `<extraction root>` 所示。\nCodeQL CLI如果找不到预期语言的qlpack，请检查是否下载了CodeQL捆绑包，而不是CodeQL CLI的独立副本。\n\n还可以运行 `codeql resolve languages` 以显示可用于数据库创建的语言。 这将列出包中 CodeQL CLI 默认支持的语言。\n\n（可选）你可以下载一些包含要运行的预编译查询的 CodeQL 包。 有关详细信息，请参阅“[使用 CodeQL 包自定义分析](/zh/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)”。\n\n```\n          `codeql resolve packs`命令在CodeQL CLI无法找到您期望可用于分析的查询包时非常有用，用于诊断问题。\n```\n\n> \\[!NOTE] 该 `codeql resolve packs` 命令在 CodeQL CLI 版本 2.19.0 及更高版本中可用。 对于较早版本的 CLI，应运行 `codeql resolve qlpacks` 命令，该命令会产生类似但详细程度较低的输出。\n\n## 后续步骤\n\n若要了解如何准备要由该 CodeQL CLI代码分析的代码，请参阅 [为 CodeQL 分析准备代码](/zh/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis)。"}