BepInEx插件打包完全指南：从环境搭建到自动化发布

1. 问题导入：插件开发者的5大痛点与解决方案

1.1 开发环境配置混乱【痛点-方案-验证】

痛点：新开发者往往需要花费数小时配置开发环境，经常出现"在我电脑上能运行"但换设备就报错的情况，特别是.NET版本冲突和依赖缺失问题频发。

解决方案：采用标准化环境配置流程，通过环境变量和专用工具管理版本依赖。

验证方法：执行环境检查命令后，所有工具版本应满足最低要求，且无冲突提示。

# Windows专用
dotnet --version && git --version && 7z --version

# Linux专用
dotnet --version && git --version && p7zip --version

[!TIP] 环境变量配置建议使用系统级而非用户级，避免不同用户登录时环境不一致。Windows通过"系统属性→高级→环境变量"配置，Linux则修改/etc/environment文件。

1.2 构建工具选择困境【新旧方案对比】

方案	适用场景	优势	劣势	推荐指数
手动编译	学习理解过程	直观可控	重复劳动多，易出错	★★☆☆☆
MSBuild脚本	单一项目构建	原生支持，配置简单	跨平台能力弱，定制复杂	★★★☆☆
CakeBuild自动化	多项目/多目标构建	跨平台，高度可定制	学习曲线较陡	★★★★★
Docker容器化	复杂环境隔离	环境一致性最高	构建速度较慢	★★★☆☆

常见陷阱：不要混用不同构建工具！例如同时使用dotnet build和Cake脚本可能导致中间文件冲突，建议选定一种工具后坚持使用。

核心知识点：

1. 环境一致性是解决"在我电脑上能运行"问题的关键
2. 工具选择应基于项目规模和团队熟悉度
3. 验证环境配置是所有开发工作的第一步

2. 核心流程：4步完成BepInEx插件打包

2.1 3步搭建基础环境【1/5】环境检查

痛点：开发者常因工具版本不匹配导致构建失败，尤其是.NET SDK版本与项目要求不符。

解决方案：建立明确的版本检查清单，通过命令行验证所有依赖工具。

验证方法：执行以下命令，确保所有工具版本符合要求。

# 检查.NET SDK版本（至少6.0）
dotnet --version

# 检查Git版本（至少2.30）
git --version

# 检查7-Zip/p7zip版本（至少21.0）
7z --version  # Windows
p7zip --version  # Linux

[!TIP] 对于Linux系统，使用dotnet --list-sdks命令可查看已安装的所有.NET版本，确保目标版本存在。

2.2 3步搭建基础环境【2/5】源码获取

痛点：直接下载ZIP包而非使用Git克隆，导致无法获取完整版本历史和子模块。

解决方案：使用Git命令克隆仓库，确保获取完整项目结构。

验证方法：检查克隆后的目录是否包含.git文件夹和所有子模块文件。

# 克隆仓库（含子模块）
git clone --recursive https://gitcode.com/GitHub_Trending/be/BepInEx
cd BepInEx

# 验证子模块
ls BepInEx.Core/Configuration  # 应显示多个.cs文件

2.3 3步搭建基础环境【3/5】依赖还原

痛点：依赖项缺失或版本冲突导致编译失败，尤其是NuGet源配置不当。

解决方案：使用dotnet restore命令配合项目根目录的nuget.config配置。

验证方法：检查obj目录下是否生成了project.assets.json文件。

# 还原解决方案所有项目依赖
dotnet restore BepInEx.sln

# 验证还原结果
ls BepInEx.Core/obj/project.assets.json  # 应显示文件存在

常见陷阱：国内用户可能遇到NuGet源访问缓慢问题，可修改nuget.config添加国内镜像源，但需注意镜像同步延迟可能导致版本不完整。

2.4 一键编译与输出整理【痛点-方案-验证】

痛点：手动编译多个项目时容易遗漏某些项目或配置，输出文件分散难以管理。

解决方案：使用MSBuild目标定义统一的输出目录和清理规则。

验证方法：检查输出目录是否只包含必要文件，无系统依赖和调试文件。

# 构建Release版本
dotnet build BepInEx.sln -c Release -p:OutputPath=../bin/Release

# 验证输出
ls bin/Release  # 应只包含项目相关DLL和必要配置文件

以下是优化的MSBuild配置示例，添加到项目文件中：

<PropertyGroup>
  <OutputPath>../bin/$(Configuration)</OutputPath>
  <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>
<Target Name="CleanupOutput" AfterTargets="Build">
  <!-- 删除系统依赖 -->
  <Delete Files="$(OutputPath)System*.dll" />
  <!-- 删除调试文件 -->
  <Delete Files="$(OutputPath)*.pdb" />
  <!-- 删除NuGet依赖清单 -->
  <Delete Files="$(OutputPath)*.deps.json" />
</Target>

核心知识点：

1. 统一的输出目录结构是后续打包的基础
2. 清理不必要的系统依赖可减小包体积
3. 自动化构建目标能确保每次构建结果一致

3. 进阶技巧：2种自动化打包方案深度对比

3.1 CakeBuild自动化方案【痛点-方案-验证】

痛点：手动执行多个构建步骤效率低下，且容易因人为疏忽导致错误。

解决方案：使用CakeBuild编写自动化脚本，将构建、测试、打包流程整合。

验证方法：执行自动化脚本后，检查输出目录是否生成符合规范的压缩包。

首先创建build.cake脚本：

var target = Argument("target", "Publish");
var configuration = Argument("configuration", "Release");
var version = Argument("version", "6.0.0");

Task("Clean")
    .Does(() =>
{
    CleanDirectory("./bin");
});

Task("Restore")
    .IsDependentOn("Clean")
    .Does(() =>
{
    DotNetRestore("./BepInEx.sln");
});

Task("Build")
    .IsDependentOn("Restore")
    .Does(() =>
{
    DotNetBuild("./BepInEx.sln", new DotNetBuildSettings
    {
        Configuration = configuration,
        OutputDirectory = $"./bin/{configuration}"
    });
});

Task("Package")
    .IsDependentOn("Build")
    .Does(() =>
{
    var zipName = $"BepInEx_{version}_{configuration}_{Environment.OSVersion.Platform}.zip";
    Zip("./bin/Release", $"./bin/{zipName}");
});

RunTarget(target);

然后执行构建命令：

# Windows专用
dotnet cake build.cake --target Package --version 6.0.0

# Linux专用
dotnet cake build.cake --target Package --version 6.0.0

[!TIP] Cake支持丰富的命令行参数，可通过dotnet cake --showdescription查看所有可用目标和参数说明。

3.2 多平台构建方案对比【新旧方案对比】

方案	实现方式	跨平台支持	配置复杂度	维护成本
手动脚本	分别编写Windows批处理和Linux Shell	需维护两套脚本	低	高
CakeBuild	单一C#脚本跨平台执行	全平台支持	中	低
Docker构建	容器内统一环境构建	理论全平台	高	中
GitHub Actions	云端多环境并行构建	全平台支持	中	低

常见陷阱：在Linux上构建Windows目标时，需确保安装了mono和msbuild，且正确设置了目标框架参数，如-f net35。

3.3 版本号管理最佳实践【痛点-方案-验证】

痛点：手动管理版本号容易出现不一致，特别是在多分支开发和发布流程中。

解决方案：使用环境变量和构建参数注入版本信息，实现版本号集中管理。

验证方法：检查构建输出文件的版本信息和压缩包名称是否包含正确版本号。

# 设置版本号环境变量（Windows PowerShell）
$env:BEPINEX_VERSION="6.0.1-beta"

# 设置版本号环境变量（Linux Bash）
export BEPINEX_VERSION="6.0.1-beta"

# 使用环境变量构建
dotnet cake build.cake --target Package --version $env:BEPINEX_VERSION

在C#代码中注入版本信息：

public class PluginInfo
{
    public const string Version = 
        System.Environment.GetEnvironmentVariable("BEPINEX_VERSION") ?? "dev";
}

核心知识点：

1. 自动化构建工具可显著减少重复劳动和人为错误
2. 版本号应集中管理并通过环境变量注入
3. 跨平台构建需考虑目标系统的特定依赖和配置

4. 实践案例：从源码到发布的完整流程

4.1 本地测试环境搭建【1/3】准备测试目录

痛点：直接在开发环境测试插件可能影响开发进度，且无法模拟真实使用场景。

解决方案：创建独立的测试环境，模拟真实安装场景。

验证方法：测试目录结构应与实际部署环境一致，且能正常加载插件。

# 创建测试目录结构
mkdir -p TestEnvironment/BepInEx/{plugins,config,core}

# 复制构建产物
cp -r bin/Release/* TestEnvironment/BepInEx/core/

# 创建测试插件目录
mkdir TestEnvironment/BepInEx/plugins/MyTestPlugin

4.2 本地测试环境搭建【2/3】配置Doorstop

痛点：Doorstop配置不正确会导致插件无法加载，且错误提示不明确。

解决方案：根据目标运行时（Mono/IL2CPP）正确配置Doorstop。

验证方法：启动测试游戏/应用程序，检查日志输出是否显示BepInEx加载信息。

对于Mono运行时，修改doorstop_config.ini：

[General]
enabled=true
targetAssembly=BepInEx/core/BepInEx.Preloader.dll

对于IL2CPP运行时，修改doorstop_config.ini：

[General]
enabled=true
targetAssembly=BepInEx/core/BepInEx.Unity.IL2CPP.dll

[!TIP] 测试时建议开启详细日志模式，在BepInEx/config/BepInEx.cfg中设置LogLevel=Debug。

4.3 本地测试环境搭建【3/3】问题排查

痛点：插件加载失败时难以定位具体原因，常见问题包括依赖缺失、版本不兼容等。

解决方案：系统排查依赖和配置，利用日志信息定位问题。

验证方法：修复问题后，插件应能正常加载并输出预期日志。

创建简单的依赖检查脚本（check_deps.sh）：

#!/bin/bash
# 检查关键依赖是否存在
REQUIRED_FILES=(
    "BepInEx.dll"
    "0Harmony.dll"
    "MonoMod.Utils.dll"
)

for file in "${REQUIRED_FILES[@]}"; do
    if [ ! -f "TestEnvironment/BepInEx/core/$file" ]; then
        echo "Missing required dependency: $file"
        exit 1
    fi
done

echo "All dependencies are present"

常见陷阱：不同Unity版本对依赖项有特定要求，例如Unity 2019+需要较新版本的0Harmony，而旧版本游戏可能需要兼容模式。

4.4 CI/CD集成示例【痛点-方案-验证】

痛点：手动执行发布流程效率低且容易出错，无法实现版本的自动化测试和发布。

解决方案：使用GitHub Actions配置自动化构建和发布流程。

验证方法：推送代码后，检查CI/CD流程是否自动完成构建、测试和发布。

创建.github/workflows/build.yml文件：

name: BepInEx Build Pipeline

on:
  push:
    tags:
      - 'v*'
  pull_request:
    branches: [ main ]

jobs:
  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive
          
      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: 6.0.x
          
      - name: Install Cake
        run: dotnet tool install -g Cake.Tool
      
      - name: Build and package
        run: dotnet cake build.cake --target Publish --version ${{ github.ref_name }}
        
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: BepInEx-Windows
          path: bin/*.zip

  build-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive
          
      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: 6.0.x
          
      - name: Install dependencies
        run: sudo apt-get install -y p7zip-full
        
      - name: Install Cake
        run: dotnet tool install -g Cake.Tool
      
      - name: Build and package
        run: dotnet cake build.cake --target Publish --version ${{ github.ref_name }}
        
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: BepInEx-Linux
          path: bin/*.zip

核心知识点：

1. 测试环境应尽可能模拟真实使用场景
2. 自动化CI/CD可确保每次发布质量一致
3. 版本号应与Git标签保持同步，便于追溯

5. 总结与最佳实践

BepInEx插件打包是从开发到发布的关键环节，通过本文介绍的环境配置、核心流程、进阶技巧和实践案例，你应该能够建立高效、可靠的打包流程。记住以下最佳实践：

1. 保持环境一致性：使用本文提供的环境检查脚本，确保开发、测试和生产环境的一致性。

2. 优先自动化：无论是本地开发还是团队协作，自动化构建工具都能显著提高效率并减少错误。

3. 版本控制严格化：采用语义化版本号，通过环境变量和CI/CD工具实现版本的集中管理。

4. 测试先行：建立完善的测试流程，在发布前验证插件在不同环境和版本下的兼容性。

通过这些方法，你不仅能解决当前的打包问题，还能为未来的插件开发和维护奠定坚实基础。随着BepInEx生态的不断发展，持续学习和优化打包流程将成为插件开发者的必备技能。

官方文档：docs/BUILDING.md