一、项目介绍
Roslyn 是微软官方开源的 .NET 编译器平台，是 C# 与 Visual Basic 两种语言编译器的现代化开源实现，源码托管在 dotnet/roslyn 仓库，属于 .NET Foundation 项目。它最具革命性的一点在于：传统编译器往往是一个"黑盒"——源码从一端进、程序集从另一端出，中间过程对开发者不可见；而 Roslyn 把编译器的全部内部步骤（词法分析、语法分析、语义绑定、发出 IL）都开放成了丰富的托管 API。
这种"编译器即服务"（Compiler-as-a-Service）的定位，让 Roslyn 不只是一个命令行编译器，更成了一整套代码分析与工具平台：Visual Studio 的智能感知、重构、"转到定义"、签名提示、格式化、浅色/着色器等语言服务，背后调用的都是 Roslyn 暴露的语法树 API、符号 API、绑定与流分析 API 以及发出（Emit）API。第三方与社区也可以基于同一套 API 编写代码分析器（Analyzer）、代码修复（Code Fix）、语法转换脚本、脚本引擎、即时窗口与自定义工具。
Roslyn 的编译器本体同时驱动 csc（C# 命令行编译器）与 vbc（VB 编译器），并被 .NET SDK、MSBuild、Visual Studio 统一调用。语言特性的设计与讨论并不在这个仓库进行：C# 语言提案去 dotnet/csharplang，VB 语言提案去 dotnet/vblang，影响两种语言的特性在 csharplang 讨论。Roslyn 仓库本身负责把已定稿的语言规范落地为编译器与 IDE 行为。
项目采用开放的协作模式：核心团队成员与外部贡献者提交的 PR 走同一套评审流程。社区可以在 GitHub Discussions 提问、交流想法，也可以加入 CSharp Community Discord 的 Roslyn 频道实时聊天。完整的架构入门见官方文档 Roslyn 架构概览。
Roslyn 之所以重要，是因为它把"编译"这一传统上一次性、不可复用的过程，变成了可以在任意进程中反复调用的托管服务。语法树是不可变的（immutable），一旦构建出来就能被安全地在多个线程间共享；任何对语法的修改都会产生一个新的语法树与新的编译对象，旧对象保持不变。这种不可变模型让编辑器的增量更新、撤销重做、以及对大型解决方案的并发分析都变得简单且无副作用，也是 Visual Studio 能够在你边敲边分析全解决方案的基础。
二、项目结构
Roslyn 仓库体量庞大，按职责可以分为编译器（Compilers）与 IDE/工作区（Features/Workspaces）两大块。编译器侧（src/Compilers/csharp 与 src/Compilers/visualbasic）包含词法分析器、语法树、符号表、绑定器、流分析与 IL 发出器；这是 csc/vbc 的本体。平台侧（src/Workspaces、src/Features、src/Features/CSharp）则承载语法树 API 之上的语言服务、重构、代码修复、导航、格式化等能力，供 Visual Studio 与其他编辑器宿主使用。
从 API 分层看（见官方架构图），最底层是编译管线（Compiler Pipeline）：Parser（解析出语法树）、Metadata Import（元数据导入）、Symbols（符号）、Binder（绑定与流分析）、IL Emitter（发出中间语言）。在管线之上是 Compiler API（即语法树 API、符号 API、绑定与流分析 API、Emit API），再往上是 Language Service，直接对应编辑器中的补全列表、查找引用、重命名、快速信息、签名帮助、提取方法、转到定义、编辑并继续等功能。
docs/ 目录收录了贡献与开发文档：Contributing-Code.md 是编码规范；Building, Debugging, and Testing on Windows 描述在 Windows 上构建、调试与运行测试的完整流程；API Review Process 说明 Roslyn 新 API 需要走的评审流程。仓库还通过 Azure DevOps 维持非常全面的持续集成矩阵：Windows Debug/Release、Unix Debug、桌面与 CoreClr 单元测试、VS 集成测试、确定性测试、分析器测试、源码构建正确性测试乃至西班牙语与 macOS 测试。
对普通使用者而言，你并不需要直接编译 Roslyn：日常通过 .NET SDK 调用的 csc、以及通过 NuGet 引用的 Microsoft.CodeAnalysis.* 包，都是官方预编译好的。只有在参与编译器/分析器开发、调试语言行为，或尝试尚未发布的特性时，才需要从源码构建。
三、版本与环境要求
普通使用 Roslyn 编译 C#/VB 代码，前提只是安装 .NET SDK——csc 编译器随 SDK 分发，dotnet build 会自动调用它。若想在自己的程序中"嵌入"代码分析能力，则通过 NuGet 引用 Microsoft.CodeAnalysis（核心语法树/符号 API）、Microsoft.CodeAnalysis.CSharp、Microsoft.CodeAnalysis.Workspaces 等包；这些包的版本与 Visual Studio / .NET 工具链对齐。
如果你要的是"最新预发布"的编译器与 IDE 服务，README 给出了三个公共 NuGet 源：Compiler（dotnet-tools 源）、IDE Services（vssdk 源）、.NET SDK（dotnet5 源）。把对应源加入 NuGet 配置后，即可在包管理器中拉取尚未正式发布的分析器与编译器预览包。
从源码构建 Roslyn 本体，对环境要求较高。按 docs 中 Windows 构建文档的约定，需要 Visual Studio 以及匹配的 .NET SDK、并启用长路径支持；测试矩阵还覆盖 Linux 与 macOS。README 强调所有工作都在 GitHub 上进行，外部贡献者提交 PR 前应先读贡献指南，并在 GitHub Discussions 提问以熟悉工作流；想找任务上手，可以关注 IDE 或 Compiler 的 help-wanted / 新手友好 issue 标签。
需要区分清楚两件事：使用 Roslyn 写/分析代码，与参与 Roslyn 编译器本身的开发，环境门槛差别极大。前者装个 SDK 或拉几个 NuGet 包即可；后者才需要完整的 Visual Studio、仓库源码与 CI 级别的测试环境。
另外，Roslyn 遵循 .NET 的支持周期：正式发布的编译器随 Visual Studio 与 .NET SDK 提供长期支持，而预览 NuGet 源上的构建主要用于反馈，不建议直接用于生产。在企业环境中若要编写自研代码分析器，建议把分析器打包成 NuGet 包并通过项目引用分发，而不是让每个开发者手动安装，这样可以保证团队规则统一、随构建自动生效。
四、本地部署步骤
方式一：通过 .NET SDK 直接使用编译器（最常见）。安装好 .NET SDK 后，csc 就在工具链内：
dotnet new console -o HelloR
cd HelloR
dotnet builddotnet build 会经由 MSBuild 调用 Roslyn 的 C# 编译器把 Program.cs 编译为 dll。你也可以直接调用 SDK 自带的 csc 做最小编译：
csc Hello.cs方式二：在自己的程序中嵌入 Roslyn 代码分析 API。新建一个控制台或类库项目，通过 NuGet 引入：
dotnet add package Microsoft.CodeAnalysis
dotnet add package Microsoft.CodeAnalysis.CSharp随后即可在代码里用 CSharpSyntaxTree.ParseText("类源码字符串") 解析语法树、用 Compilation.Create 创建编译对象、用 SemanticModel 获取类型信息。这是编写代码分析器、重构工具、脚手架脚本的基础。
方式三：使用预发布 NuGet 源体验最新特性。按 README，在 NuGet 配置中加入下列源后即可拉预览包：
https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json
https://pkgs.dev.azure.com/azure-public/vside/_packaging/vssdk/nuget/v3/index.json
https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet5/nuget/v3/index.json方式四：从源码构建 Roslyn（贡献者场景）。先从 GitHub 仓库 clone 源码，再按 docs/contributing/Building, Debugging, and Testing on Windows.md 的说明在 Windows 上运行构建脚本，用 Visual Studio 打开解决方案进行调试、跑测试。这一步会还原大量依赖，对磁盘与内存要求较高。
建议第一次参与时，从 help-wanted 标签下的"新手友好"issue 入手：IDE 类 issue 对应工作区与语言服务，Compiler 类 issue 对应编译器管线；认领前先在 issue 下留言，避免多人重复劳动。提交 PR 前务必跑通本地测试，并遵循仓库的编码规范与 API 评审要求。
五、浏览器端部署
Roslyn 是编译器与代码分析平台，本身没有面向终端用户的浏览器界面。所谓"浏览器端"指的是：基于 Roslyn 构建出来的 Web 应用，或把 Roslyn 作为分析后端的在线代码运行/教学站点在浏览器中被使用。
典型场景是在线 C# 编辑器与教学平台：在浏览器里输入 C# 代码，前端把代码文本发给后端服务，后端用 Roslyn 的 SyntaxTree/SemanticModel 做语法高亮、错误提示、补全分析，再把结果回传浏览器；甚至可以用 Roslyn 的 Emit API 在内存中编译并（在沙箱里）运行代码。这种"编译器即服务"正是 Roslyn 区别于旧式黑盒编译器的地方。
如果你只是在本地用 Visual Studio / VS Code 写 C#，那么浏览器这一环并不存在——Roslyn 以进程内语言服务的形式运行在 IDE 后台，智能感知、红波浪线、重构菜单都是它直接产出的。把 Roslyn 暴露到浏览器服务端时，要特别注意安全：在服务端任意编译并执行用户上传的代码有极高风险，必须放在隔离沙箱（容器、受限权限进程）中运行，绝不能直接在宿主进程里 Emit 并执行不可信代码。
另一个常见的"浏览器侧"用法是静态站点生成与文档工具链：在构建阶段用 Roslyn 解析源码，自动生成 API 文档、依赖关系图、代码示例与迁移报告，再把结果渲染成静态网页。这类只读分析不执行用户代码，风险低，是非常安全的服务端 Roslyn 应用形态。
六、API 用法
Roslyn 暴露给开发者的核心 API 有四块：语法树 API（处理词法与语法）、符号 API（处理类型、方法、字段等语义实体）、绑定与流分析 API（判断表达式的含义与数据流）、Emit API（把编译产出为程序集）。一个最小示例：
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
var tree = CSharpSyntaxTree.ParseText("public class C { public int F; }");
var root = tree.GetRoot();
Console.WriteLine(root.ToString());
var compilation = CSharpCompilation.Create("MyComp",
syntaxTrees: new[] { tree },
references: new[] {
MetadataReference.CreateFromFile(typeof(object).Assembly.Location)
});上面这段代码把一段 C# 文本解析成语法树并打印出来，再创建一个编译对象、引用运行时程序集。你可以遍历语法树的节点、查找特定语法元素、读取 SemanticModel 拿到"这个 F 字段的类型是什么"。
基于这套 API，社区与微软构建了大量上层能力：分析器（Analyzer，诊断代码规范问题）、代码修复（CodeFix，一键改正）、重构（Refactoring）、语法转换（如把旧 API 调用批量迁移到新 API）。在 Visual Studio 中，这些能力以"灯泡"建议的形式呈现。完整 API 参考见 Roslyn 架构与 API 文档。
七、常见问题 FAQ
问一：我只是想编译 C# 代码，需要单独安装 Roslyn 吗？
答：不需要。安装 .NET SDK 后 csc 已经内置，dotnet build / dotnet run 会自动调用 Roslyn。只有要在自己程序里做语法分析、写分析器时，才需要通过 NuGet 引用 Microsoft.CodeAnalysis.* 包。
问二：想提一个 C# 新语言特性，应该去哪个仓库？
答：语言特性的设计与讨论在 dotnet/csharplang（C#）或 dotnet/vblang（VB），不在 dotnet/roslyn。Roslyn 负责把已定稿的语言规范实现成编译器；Roslyn 自身 API 的新增则要走仓库的 API 评审流程。
问三：NuGet 里拉不到最新的预览编译器/分析器？
答：预览包发布在 README 列出的三个公共 Azure DevOps NuGet 源（dotnet-tools、vssdk、dotnet5），需要先把对应源加入 NuGet 配置并勾选"包含预发行版"。这些源随官方每日构建持续更新。
问四：从源码构建 Roslyn 失败，常见原因是什么？
答：一是未启用 Windows 长路径支持，深层路径报错；二是 Visual Studio 工作负载或 .NET SDK 版本不匹配；三是磁盘/内存不足以还原与编译庞大的依赖树。请严格按 docs 中的 Building, Debugging, and Testing on Windows 文档操作。
问五：能把用户在浏览器里写的 C# 代码直接用 Roslyn 编译运行吗？
答：技术上可以用 Emit API 在内存中编译，但绝不能在宿主进程里直接执行不可信代码。务必把编译与运行放在隔离沙箱（容器、低权限进程、限时限额）中，并禁用危险 API，否则会有任意代码执行与资源耗尽风险。
问六：Roslyn 分析器和普通代码检查工具有什么区别？
答：它直接基于语义模型而非正则或文本扫描，因此能理解类型、作用域、继承与数据流，给出真正准确的诊断与代码修复，并且能随项目一起编译、在 CI 中作为构建警告强制生效，而不只是编辑器里的提示。
问七：写好的分析器如何分发到团队？
答：把分析器类库打包为 NuGet 包，在目标项目中通过 PackageReference 引用，或通过 EditorConfig 控制其严重级别。这样所有开发者在本地与 CI 构建时都会自动运行同一套规则，无需各自安装 VSIX。
相关链接：官方仓库 · 架构与 API 文档 · C# 语言设计 · 贡献指南 · Discord 社区
说明：本文命令、NuGet 源与 API 分层均参照官方 README 整理，实际版本与包名请以仓库 main 分支及官方文档最新说明为准。