从0到1跑通 .NET Runtime：环境、目录、构建与排错的完整任务流
【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime
.NET runtime 是微软开源的跨平台 .NET 运行时仓库，一套代码同时覆盖云端、桌面、移动端和 IoT 场景。仓库由三大块组成：CoreCLR 与 Mono 两个运行时实现、BCL 类库，以及负责启动应用的 host 与安装器。这篇文章按你从克隆仓库到跑通首次构建的真实顺序展开，先备好环境和 SDK，再理解目录和组件划分，最后把新手最容易踩的报错一次讲清，适合第一次接触 .NET 运行时源码的同学。
备齐平台依赖与构建 SDK
这个仓库支持在 Windows、Linux、macOS、FreeBSD 上构建，但不是所有芯片组合都支持。先对照下表确认你的开发机在矩阵内，再装依赖：
| 芯片 | Windows | Linux | macOS | FreeBSD |
|---|---|---|---|---|
| x64 | 支持 | 支持 | 支持 | 支持 |
| x86 | 支持 | — | — | — |
| Arm32 | — | 支持 | — | — |
| Arm64 | 支持 | 支持 | 支持 | — |
三大平台的核心依赖如下，仓库提供了一键脚本（Linux 最小内存要求 1GB）：
| 平台 | 必备工具 | 详细说明 |
|---|---|---|
| Linux | cmake ≥3.26、llvm、lld、clang、build-essential、libicu-dev、libssl-dev、libkrb5-dev、ninja-build、python3 | docs/workflow/requirements/linux-requirements.md |
| macOS | Xcode 命令行工具、CMake ≥3.26、icu4c、python3、ninja、pkg-config | docs/workflow/requirements/macos-requirements.md |
| Windows | Git ≥2.22、Visual Studio 2022 17.8+（.NET 桌面 + C++ 桌面工作负载）、启用长路径 | docs/workflow/requirements/windows-requirements.md |
📦 依赖装好后，SDK 不用手动找。仓库根目录的global.json已声明所需版本11.0.100-rc.1.26420.103，跑一次官方脚本即可自动下载到本地.dotnet目录：
./eng/common/dotnet.sh # Windows 用 eng/common/dotnet.cmd克隆仓库并完成首次构建
克隆全量历史约 400–500MB 网络流量，检出后本地占 1–1.5GB；单平台构建产物会再吃 10–20GB，动手前留够磁盘。
git clone https://gitcode.com/GitHub_Trending/runtime6/runtime cd runtime构建入口是根目录的build.sh（Windows 为build.cmd）。不带任何参数它会以 Debug 配置构建整个仓库的本机版本；日常开发只构建需要的子集更快，用-subset指定：
./build.sh -subset clr # Windows: build.cmd -subset clr常用子集对照：
| 子集 | 构建内容 |
|---|---|
clr | CoreCLR 运行时 + System.Private.CoreLib |
libs | 全部 BCL 类库（不含测试） |
host | dotnet 共享宿主及托管库 |
packs | 共享框架包、归档、安装器 |
mono | Mono 运行时及其 CoreLib |
子集可用+串联，例如./build.sh -subset clr+libs -configuration Release。构建完成后，主产物在artifacts/bin/coreclr/<OS>.<架构>.<配置>/（如linux.x64.Release），里面最关键的三个文件是：corerun（命令行宿主，Windows 下为corerun.exe）、coreclr（运行时本体，Linux 下为libcoreclr.so）、System.Private.CoreLib.dll（基础托管库）。日志在artifacts/log/，中间产物在artifacts/obj/coreclr/。
认清三大组件与构建配置
三大组件的代码位置一目了然：CoreCLR 在src/coreclr/、Mono 在src/mono/、类库在src/libraries/、native 依赖（host、corehost 等）在src/native/。其中 CoreLib（System.Private.CoreLib）是最底层的托管库，必须与运行时用同一套配置构建；而普通类库可以独立选择自己的配置。
构建有三档配置，选择取决于你要干什么：
| 配置 | 优化 | 断言 | 典型用途 |
|---|---|---|---|
| Debug | 无 | 开启 | 调试产品，速度最慢 |
| Checked | 有 | 开启 | CoreCLR 专属，CI 跑测试常用 |
| Release | 有 | 关闭 | 性能剖析，速度最快 |
🔧 配置组合有讲究：改运行时时建议运行时用 Debug、类库用 Release；改类库时反过来（运行时 Release、类库 Debug），这样内循环迭代最快。生成完整 NuGet 包和安装器需要一次构建clr+libs+host+packs四个子集，产物会落在artifacts/packages/<配置>/Shipping/。
报错速查：新手最常碰的 5 个坑
| 现象 | 原因 | 处理 |
|---|---|---|
| 提示 required .NET SDK wasn't found | 本地还没有 global.json 声明的 SDK | 运行./eng/common/dotnet.sh自动安装到.dotnet |
克隆时报Unable to create file: Filename too long（Windows） | Git for Windows 默认 260 字符路径限制 | 管理员终端执行git config --system core.longpaths true，并按微软文档启用 Windows 长路径 |
| 一个"未用变量"警告直接中断构建 | 仓库把警告当作错误（含代码风格警告） | 构建前设环境变量TreatWarningsAsErrors=false，build.sh/cmd 与 dotnet build 都会遵守 |
只传了-rc/-lc却构建测试失败 | 构建 clr 时 apphost 默认走 Debug，与测试不匹配 | 构建 clr 时务必同时带上-c或-hc，让相关组件保持同配置 |
| 构建异常缓慢、磁盘告急 | 该仓库本身体量就大 | 确保 10–20GB 可用空间；单次只构建必要子集，必要时./build.sh -clean清理 artifacts |
另外两个提醒：CoreCLR 与 Mono 都可用时，一般日常开发用 CoreCLR，需要轻量运行时（如浏览器、移动）再考虑 Mono，二者构建文档分别在 docs/workflow/building/coreclr/README.md 和 docs/workflow/building/mono/README.md。
先跑通clr子集、确认产物目录里能找到 corerun，再去叠加 libs 和 host 子集——第一次构建不求全量，跑通再谈效率。
【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
