# 数据库初始化 \[管道] 创建空的 CodeQL 数据库。 > \[!NOTE] > 此内容描述了 CodeQL CLI 的最新版本。 有关此版本的详细信息，请参阅 。 > > 若要查看早期版本中此命令可用选项的详细信息，请在终端中使用 `--help` 选项运行命令。 ## 概要 ```shell copy codeql database init --source-root= [--language=[,...]] [--github-auth-stdin] [--github-url=] [--extractor-option=] ... -- ``` ## Description ``` \[管道] 创建空的 CodeQL 数据库。 ``` 为还没有原始 QL 数据集但已准备好运行提取程序步骤的 CodeQL 数据库创建主干结构。 此命令完成后，运行一个或多个 [codeql database trace-command](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-trace-command) 命令，然后运行 [codeql database finalize](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-finalize)，以准备数据库进行查询。 （这样做的一部分作用是解析相应语言包的位置并将其存储在数据库元数据中，这样就无需在每个提取命令中重新执行。 无论如何，在提取操作过程中切换提取程序都是无效的。） ## 选项 ### 主要选项 #### `` ``` \[必选] 要创建的 CodeQL 数据库的路径。 此目录将被创建，且_不得_已存在（但其父目录必须存在）。 ``` 如果指定了 `--db-cluster` 选项，此目录本身不会是数据库，而是\_包含\_从同一源根构建的多种语言的数据库的目录。 重要的是，此目录不位于生成过程会干扰的位置。 例如，Maven 项目的 `target` 目录不是合适的选择。 #### `-s, --source-root=` ``` \[必选] 源代码根目录。 在许多情况下，这将是签出根目录。 其中的文件被视为此数据库的主要源文件。 在某些输出格式中，文件将由此目录中的相对路径引用。 ``` #### `--[no-]overwrite` ``` \[高级] 如果数据库已存在，则删除它并继续执行此命令，而非失败。 如果该目录存在，但看起来不是数据库，则会抛出错误。 ``` #### `--[no-]force-overwrite` ``` \[高级] 如果数据库已存在，即使它看起来不是数据库，也删除它并继续执行此命令，而非失败。 应谨慎使用此选项，因为它可能以递归方式删除整个数据库目录。 ``` #### `--codescanning-config=` ``` \[高级] 读取 Code Scanning 配置文件，该文件指定有关如何创建 CodeQL 数据库以及在后续步骤中运行哪些查询的选项。 有关此配置文件格式的更多详细信息，请参阅 [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning)。 要在后续步骤中从此文件运行查询，请在未指定任何其他查询的情况下调用 [codeql database analyze](/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-analyze)。 ``` #### `--[no-]db-cluster` 为不同语言创建数据库“群集”（其中每个数据库都是命令行上给定的目录的子目录），而不是创建单一数据库。 #### `-l, --language=[,...]` 新数据库将用于分析的语言。 使用 [codeql resolve languages](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/resolve-languages) 获取搜索路径上发现的可插入语言提取程序的列表。 如果给定了 `--db-cluster` 选项，这可能会多次显示，或者该值可以是以逗号分隔的语言列表。 如果省略此选项，并且要分析的源根目录是 GitHub 存储库的签出，则 CodeQL CLI 将调用 GitHub API 以尝试自动确定要分析的语言。 请注意，要执行此操作，必须在环境变量 GITHUB\_TOKEN 中或通过使用 `--github-auth-stdin` 选项的标准输入来提供 GitHub PAT 令牌。 #### `--build-mode=` 将会用于创建数据库的生成模式。 根据要分析的语言选择生成模式： ``` `none`：将创建数据库，而不构建源根。 ``` 适用于 C#、Java、JavaScript/TypeScript、Python 和 Ruby。 ``` `autobuild`：将通过尝试自动构建源根来创建数据库。 适用于 C/C++、C#、Go、Java/Kotlin 和 Swift。 `manual`：将通过使用手动指定的构建命令构建源根来创建数据库。 适用于 C/C++、C#、Go、Java/Kotlin 和 Swift。 ``` 使用 `--command` 创建数据库时，不需要额外指定 '--build-mode manual'。 自 `v2.16.4` 起可用。 #### `--[no-]allow-missing-source-root` ``` \[高级] 即使指定的源根不存在，也继续执行。 ``` #### `--[no-]begin-tracing` ``` \[高级] 创建一些可用于设置“间接构建跟踪”的脚本，当没有明确的构建命令时，该跟踪允许集成到现有构建工作流中。 有关何时以及如何使用此功能的信息，请参阅 [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis) 上的文档。 ``` ### 基线计算选项 #### `--[no-]calculate-baseline` ``` \[高级] 计算有关待分析代码的基线信息，并将其添加到数据库中。 默认情况下，除非源根目录是文件系统的根目录，否则会启用此选项。 此标志可用于禁用或强制启用行为，即使在文件系统的根目录中也是如此。 ``` #### `--[no-]sublanguage-file-coverage` ``` \[仅 GitHub.com 和 GitHub Enterprise Server v3.12.0+] 使用子语言文件覆盖率信息。 这会为共享 C 和 C++、Java 和 Kotlin，以及 JavaScript 和 TypeScript 等 CodeQL 提取程序包的语言计算、显示和导出单独的文件覆盖信息。 ``` 自 `v2.15.2` 起可用。 ### 提取程序选择选项 #### `--search-path=[:...]` 可在其中找到提取程序包的目录列表。 目录可以是提取程序包本身，也可以是包含提取程序作为直接子目录的目录。 如果路径包含多个目录树，则目录树的顺序定义了各自之间的优先级：如果目标语言在多个目录树中匹配，则给定的第一个目录树优先。 与 CodeQL 工具链本身捆绑的提取程序始终都能找到，但如果需要单独使用分布式提取程序，则需要提供此选项（或者更佳方式是，在每用户配置文件中设置 `--search-path`）。 （注意：在 Windows 上，路径分隔符为 `;`）。 ### 用于配置如何调用 GitHub API 以自动检测语言的选项。 #### `-a, --github-auth-stdin` 通过标准输入接受 GitHub Apps 令牌或个人访问令牌。 这会替代 GITHUB\_TOKEN 环境变量。 #### `-g, --github-url=` 要使用的 GitHub 实例的 URL。 如果省略，CLI 将尝试从签出路径自动检测此项，如果这不可行，则默认为 ### 用于配置包管理器的选项。 #### `--registries-auth-stdin` 通过传递逗号分隔的 \=\ 对列表，向 GitHub Enterprise Server 容器注册表进行身份验证。 例如，可以传递 `https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` 向两个 GitHub Enterprise Server 实例进行身份验证。 这会替代 CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN 环境变量。 如果只需向 github.com 容器注册表进行身份验证，则可以改用更简单的 `--github-auth-stdin` 选项进行身份验证。 ### 用于配置 Windows 跟踪的选项 #### `--trace-process-name=` ``` \[仅限 Windows] 初始化跟踪时，将跟踪器注入名称与此参数匹配的 CodeQL CLI 的父进程。 如果多个父进程具有此名称，则会选择进程树中最底下的一个。 此选项将替代 `--trace-process-level`，因此，如果同时传递了两者，则仅使用此选项。 ``` #### `--trace-process-level=` ``` \[仅限 Windows] 初始化跟踪时，将跟踪器注入当前进程上方的此数量的父进程中，其中 0 对应于调用 CodeQL CLI 的进程。 如果未传递任何自变量，则 CLI 的默认行为是注入调用流程的父级，但对于 GitHub Actions 和 Azure Pipelines 有一些特殊情况存在。 ``` ### 用于配置间接生成跟踪的选项 #### `--no-tracing` ``` \[高级] 不跟踪指定的命令，而是依赖它直接生成所有必要数据。 ``` #### `--extra-tracing-config=` ``` \[高级] 跟踪器配置文件的路径。 这可用于修改生成跟踪器的行为。 它可用于选取作为生成命令的一部分运行的编译器进程，并触发其他工具的执行。 提取程序将提供在大多数情况下应该都能工作的默认跟踪器配置文件。 ``` ### 用于控制提取程序行为的选项：仅应用于间接跟踪环境 #### `-O, --extractor-option=` 设置 CodeQL 提取程序的选项。 `extractor-option-name` 应为 \_name.group1.group2.option\_name 或 group1.group2.option\_name 格式。 如果 `extractor_option_name` 以提取程序名称开头，则指示的提取程序必须声明选项 group1.group2.option\_name。 否则，声明选项 group1.group2.option\_name 的任何提取程序都将设置该选项。 `value` 可以是任何不包含换行符的字符串。 可以重复使用此命令行选项来设置多个提取程序选项。 如果为同一提取程序选项提供多个值，则行为取决于提取程序选项所需的类型。 字符串选项将使用提供的最后一个值。 数组选项将按顺序使用提供的所有值。 使用此命令行选项指定的提取程序选项在通过 `--extractor-options-file` 给定的提取程序选项之后进行处理。 传递给 codeql database init 或 `codeql database begin-tracing` 时，选项将仅应用于间接跟踪环境。 如果工作流还调用 [codeql database trace-command](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-trace-command)，则还需根据需要传递选项。 请参阅 以了解有关 CodeQL 提取程序选项的详细信息，包括如何列出每个提取程序声明的选项。 #### `--extractor-options-file=` 指定提取程序选项捆绑文件。 提取程序选项捆绑文件是设置提取程序选项的 JSON 文件（扩展名为 `.json`）或 YAML 文件（扩展名为 `.yaml` 或 `.yml`）。 该文件必须具有顶级映射键“extractor”，并且其下必须具有作为二级映射键的提取程序名称。 进一步的映射级别表示嵌套的提取程序组，字符串和数组选项是具有字符串和数组值的映射条目。 按指定的顺序读取提取程序选项捆绑文件。 如果不同的提取程序选项捆绑文件指定了相同的提取程序选项，则行为取决于提取程序选项所需的类型。 字符串选项将使用提供的最后一个值。 数组选项将按顺序使用提供的所有值。 使用此命令行选项指定的提取程序选项在通过 `--extractor-option` 给定的提取程序选项之前进行处理。 传递给 codeql database init 或 `codeql database begin-tracing` 时，选项将仅应用于间接跟踪环境。 如果工作流还调用 [codeql database trace-command](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-trace-command)，则还需根据需要传递选项。 请参阅 以了解有关 CodeQL 提取程序选项的详细信息，包括如何列出每个提取程序声明的选项。 ### 常用选项 #### `-h, --help` 显示此帮助文本。 #### `-J=` ``` \[高级] 向运行命令的 JVM 提供选项。 ``` （请注意，无法正确处理包含空格的选项。） #### `-v, --verbose` 以增量方式增加输出的进度消息数。 #### `-q, --quiet` 以增量方式减少输出的进度消息数。 #### `--verbosity=` ``` \[高级] 明确将详细级别设置为 errors、warnings、progress、progress+、progress++、progress+++ 之一。 重写 `-v` 和 `-q`。 ``` #### `--logdir=` ``` \[高级] 将详细日志写入指定目录中的一个或多个文件，生成的文件名包含时间戳和正在运行的子命令名称。 ``` （要使用可以完全控制的名称编写日志文件，请根据需要提供 `--log-to-stderr` 并重定向 stderr。） #### `--common-caches=` ``` \[高级] 控制磁盘上缓存数据的位置，这些数据将在 CLI 的多次运行之间保留，例如下载的 QL 包和编译的查询计划。 如果未明确设置，则默认为用户主目录中名为 `.codeql` 的目录；如果尚不存在，则会创建该目录。 ``` 自 `v2.15.2` 起可用。