# 创建并使用 CodeQL 包

可以使用 CodeQL 包创建、共享、依赖和运行 CodeQL 查询和库。

## 关于 CodeQL 包和 CodeQL CLI

```
          CodeQL 包用于创建、共享、依赖和运行 CodeQL 查询和库。
```

可以使用 `pack` 命令在 CodeQL CLI 中创建 CodeQL 包、添加或安装依赖项，以及更新依赖项。 还可以使用CodeQL命令发布和下载`pack`包。

## 创建 CodeQL 包

可以通过从项目的签出根目录运行以下命令来创建 CodeQL 包：

```shell
codeql pack init <scope>/<pack>
```

必须指定以下内容：

* `<scope>`：要发布到的组织 GitHub 或用户帐户的名称。

* `<pack>`：你正在创建的包的名称。

该 `codeql pack init` 命令为 CodeQL 包创建目录结构和配置文件。 默认情况下，此命令会创建查询包。 如果要创建库包，必须编辑 `qlpack.yml` 文件，通过包含 `library:true` 属性将文件显式声明为库包。

## 创建 CodeQL 模型包

> \[!NOTE]
> CodeQL 模型包目前包含在 公共预览版 中，可能会更改。 C/C++、C#、Java/Kotlin、Python、Ruby 和 Rust 分析支持模型包。
>
> CodeQL 的 CodeQL 扩展中的 Visual Studio Code 支持对  C#、Java/Kotlin、Python 和 Ruby 的依赖项建模。

模型包可用于扩展 code scanning 分析，以识别默认情况下不支持的库和框架。 模型包使用作为 YAML 实现的数据扩展，并描述如何为新依赖项添加数据。 指定模型包后，该包中的数据扩展插件将自动添加到 code scanning 分析中。 有关模型包和数据扩展插件的详细信息 CodeQL ，请参阅 [使用 CodeQL 模型编辑器](/zh/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor)。

模型包是 CodeQL 文件中具有以下特征的 `qlpack.yml` 包：

* 其定义 `library: true`。
* 其没有依赖项。
* 其有一个或多个 `extensionTargets`。
* 其具有指向一个或多个数据扩展文件的 `dataExtensions` 属性。

如果模型包位于指定的版本范围内，则模型包会将指定的数据扩展注入到已在 `extensionTargets` 中命名的每个查询包中。 例如：

```yaml
name: my-repo/my-java-model-pack
version: 1.2.3
extensionTargets:
  codeql/java-all: ~1.2.3
  codeql/util: ~4.5.6
dataExtensions:
  - models/**/*.yml
```

在此示例中，模型包会将 `models/**/` 中的所有数据扩展注入到版本范围是 `codeql/java-all` 到最高 `1.2.3`（含该版本）的 `1.3.0` 查询包和版本范围是 `codeql/util` 到最高 `4.5.6`（含该版本）的 `4.6.0` 查询包中。 有关详细信息，请参阅 npm 文档中的[使用语义化版本控制](https://docs.npmjs.com/about-semantic-versioning#using-semantic-versioning-to-specify-update-types-your-package-can-accept)和[语义化版本控制规范](https://semver.org/)。

创建模型包后，可以像其他 CodeQL 包一样发布模型包。 有关详细信息，请参阅“[发布及使用 CodeQL 包](/zh/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs)”。 然后，可以在分析中通过 `--model-packs` 选项使用 code scanning 已发布的模型包。 有关详细信息，请参阅“[使用 CodeQL 包自定义分析](/zh/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies)”。

## 在 CodeQL 包中安装和添加依赖项

> \[!NOTE]
> 这仅适用于 CodeQL 查询和库包。

可以使用命令`codeql pack add`为CodeQL包添加依赖项。 必须指定范围、名称和（可选）兼容版本范围。

```shell
codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>
```

如果未指定版本范围，则将添加最新版本。 否则，将添加满足所请求范围的最新版本。

此命令使用请求的依赖项更新 `qlpack.yml` 文件，并将其下载到包缓存中。 请注意，此命令将重新格式化文件并删除所有注释。

还可以手动编辑 `qlpack.yml` 文件以包含依赖项，并使用以下命令安装依赖项：

```shell
codeql pack install
```

此命令将所有依赖项下载到本地磁盘上的共享缓存。

> \[!NOTE]
>
> * 运行 `codeql pack add` 和 `codeql pack install` 命令将生成或更新 `codeql-pack.lock.yml` 文件。 此文件应签入版本控制。
>   `codeql-pack.lock.yml` 文件包含包使用的确切版本号。 有关详细信息，请参阅[关于 codeql-pack.lock.yml 文件](/zh/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs##about-codeql-packlockyml-files)。
> * 默认情况下，`codeql pack install` 将从 Container registry 安装依赖项到 GitHub.com。 可以通过从GitHub Enterprise ServerContainer registry创建`qlconfig.yml`文件来安装依赖项。 有关详细信息，请参阅文档中的 [](/zh/enterprise-server@3.20/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs)GitHub Enterprise Server。

## 组织 CodeQL 包的目录结构

包CodeQL在其根目录中必须包含一个名为`qlpack.yml`的文件。 在`qlpack.yml`文件中，`name:`字段必须有一个值，该值符合`<scope>/<pack>`的格式，其中`<scope>`指的是GitHub，即包将发布到的组织或用户帐户，而`<pack>`是包的名称。

此外，包含 CodeQL 测试的查询包和库包包含包含 `codeql-pack.lock.yml` 包解析依赖项的文件。 此文件是在调用 `codeql pack install` 命令期间生成的，不应手动编辑，并且应将其添加到版本控制系统中。

包内的其他文件和目录应按逻辑组织。 例如，通常：

* 查询按特定类别组织到目录中。
* 对特定产品、库和框架的查询组织为其自己的顶级目录。

## 自定义下载的 CodeQL 包

试验更改包的建议方法是克隆包含其源代码的存储库。

如果没有可用的源存储库，并且你需要基于从 Container registry中下载的包进行基本修改，请注意，下载后不会修改或自定义这些包，并且其格式将来可能会更改，而无需太多注意。 如果需要修改内容，建议在下载包后执行以下步骤：

* 修改 \_\_ 中的包`qlpack.yml`，以避免与未修改包的结果混淆。

* 删除解压缩目录结构中任意位置的名为 `*.qlx` 的所有文件。 这些文件包含预编译的查询版本，并且在某些情况下，CodeQL 将会优先使用这些版本，而不是您已修改的 QL 源。