跳到主要内容

教程：使用自定义脚本作为资产缓存源（以 NuGet 为存储后端）

本节介绍的是 kmpkg 的实验性功能，该功能可能随时变更或移除。

本示例中，我们将通过编写脚本实现制品的还原（restore）和推送（push）逻辑，从而把 NuGet 包源配置为 kmpkg 的资产缓存源。

前提条件​

  • nuget.exe 可执行文件
  • 一个可用的 NuGet 包源

步骤 1：创建 asset-source.nuspec​

新建一个 NuGet 包规范（.nuspec）模板文件，内容如下：

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>$sha$</id>
        <version>1.0.0</version>
        <description>kmpkg download asset</description>
        <authors>kmpkg</authors>
    </metadata>
    <files>
        <file src="$file$" />
    </files>
</package>

步骤 2：创建资产提供程序脚本​

接下来需要编写脚本，实现核心逻辑：若 NuGet 源中存在目标包，则从源下载；若不存在，则先从原始地址获取资产，再将其上传至 NuGet 源。

创建 asset-provider.bat 批处理文件，填入以下内容（请将 NuGet 源 URL 和 asset-source.nuspec 路径替换为你系统中的实际值）：

@echo off
set url=%1
set sha512=%2
set dst=%3
set "_dst=%dst:/=\%"
set "_sha512=%sha512:~0,90%"

cd /d %~dp3
%NUGET% install %sha512:~0,90% -Source https://your-nuget-feed-url
echo.
if exist %_sha512%.1.0.0 (
    echo "Pull from the NuGet feed"
    cd %_sha512%.1.0.0

    REM 假设下载的是文件而非目录
    echo "F" | xcopy /f *.part %_dst%
) else (
    echo "Fetch from the url"
    curl.exe -L %url% --create-dirs --output %dst%
    REM 替换为 asset-source.nuspec 的实际路径
    %NUGET% pack C:\path\to\asset-source.nuspec -BasePath %~dp3 -Properties "sha=%_sha512%;file=%dst%" -OutputDirectory %TEMP%
    %NUGET% push -ApiKey az -SkipDuplicate %TEMP%\%_sha512%.1.0.0.nupkg -Source https://your-nuget-feed-url
)

步骤 3：配置资产缓存源​

脚本创建完成后，需配置环境变量，让 kmpkg 识别并使用该脚本作为资产缓存源：

$env:X_KMPKG_ASSET_SOURCES="clear;x-script,C:/path/to/asset-provider.bat {url} {sha512} {dst};x-block-origin"
$env:NUGET="C:/path/to/nuget.exe"
$env:KMPKG_KEEP_ENV_VARS="NUGET"
说明

请务必将脚本路径（C:/path/to/asset-provider.bat）和 nuget.exe 路径（C:/path/to/nuget.exe）替换为你系统中的实际路径。

环境变量说明​

  • X_KMPKG_ASSET_SOURCES：kmpkg 资产缓存源的核心配置变量，本示例中：

    • clear：清空默认的资产缓存位置；
    • x-script：将自定义脚本注册为资产缓存源，格式为 x-script,脚本路径 {参数1} {参数2} {参数3}，其中 {url}/{sha512}/{dst} 是 kmpkg 自动填充的内置参数（分别对应资产地址、SHA512 哈希、本地存储路径）；
    • x-block-origin：强制所有资产下载均从配置的缓存源获取，禁止直接访问原始地址。

  • KMPKG_KEEP_ENV_VARS：kmpkg 构建时会创建干净的环境，该变量用于保留指定的系统环境变量。此处添加 NUGET，确保脚本中引用的 %NUGET% 变量能正常指向 nuget.exe 路径。

效果验证​

配置完成后，每当 kmpkg 下载新资产时，脚本会自动将其打包并上传至你的 NuGet 源；后续再需该资产时，会直接从 NuGet 源拉取，无需重复下载。

缓存资产的 NuGet 包名由“资产 SHA512 哈希（前90位）+ 版本号（1.0.0）”组成。若需自定义包名，可修改 asset-source.nuspec 模板和脚本中的命名逻辑（例如加入资产名称、版本等信息）。