必须同时满足.NET SDK≥6.0.400、QDK CLI≥1.25.299873、VSCode启用Q#语言服务器、项目用dotnet new console -lang Q#创建且含host.cs，四者缺一不可。
直接装好就能写，但漏掉任一环节都会卡在 dotnet run 报错或 .qs 文件没语法高亮。
确认 .NET SDK 和 QDK CLI 版本是否匹配
Q# 项目依赖 .NET 运行时和 QDK 工具链协同工作，不是装了最新版就一定兼容。2026 年 5 月起，Azure Quantum v3.0 API 要求最低为 .NET 6.0.400+ 和 QDK CLI ≥ 1.25.299873。
- 运行
dotnet --version，输出必须是6.0.400或更高（如6.0.422） - 运行
dotnet iqsharp --version，若提示命令未找到，说明 QDK CLI 没装：执行dotnet tool install -g Microsoft.Quantum.Sdk - 若已安装但版本过低，先卸载再重装：
dotnet tool uninstall -g Microsoft.Quantum.Sdk→ 重跑 install 命令 - 不建议用
dotnet new -i Microsoft.Quantum.ProjectTemplates单独装模板——它可能滞后于 CLI，优先靠 CLI 自动注入
VSCode 扩展必须启用语言服务器
只装 “Q# Development Kit” 扩展还不够，VSCode 默认可能禁用其核心服务。没有 LSP（Language Server Protocol），就没有补全、跳转、错误诊断。
- 打开 VSCode 设置（
Ctrl+,），搜索qsharp.enableLanguageServer - 确保该配置项为
true（不是灰色继承值，要手动打勾或设为 true） - 重启 VSCode 后，新建一个
test.qs文件，观察右下角状态栏是否显示 “Q#” 和 “Ready” 字样 - 如果仍无响应，检查扩展面板中该插件是否被禁用，或执行命令面板（
Ctrl+Shift+P）输入 “Q#: Restart Language Server”
创建项目必须用 dotnet new console -lang Q#
别手建文件夹 + 手动写 .csproj，Q# 项目结构有隐含约定：C# 宿主程序（host.cs）负责调用，Q# 逻辑（Program.qs）不能独立执行。
- 终端执行：
dotnet new console -lang Q# -o MyQuantumApp（注意是console，不是classlib或qsharp） - 进入目录后运行
code .，不要用“Open Folder”打开父级目录，否则扩展可能无法识别上下文 - 首次打开时，VSCode 会自动还原 NuGet 包并启动 IQ# 内核；若右下角长时间显示 “Loading…” 或报
Failed to start IQ# kernel，多半是 .NET 或 QDK CLI 版本不匹配 -
Program.qs中的@EntryPoint()函数会被host.cs的Main方法自动发现并执行，无需改入口点
运行失败常见原因和快速验证点
执行 dotnet run 报错，90% 都出在这几个位置，按顺序排查比重装快得多。
- 终端当前路径是否在项目根目录？即含有
.csproj和host.cs的那一层 - 是否误删了
host.cs？它不是可选文件，Q# 代码必须由 C# 宿主驱动 - 是否在
Program.qs中写了非法操作？例如未Reset(q)就释放量子比特，会触发 QDK 运行时拒绝执行 - 模拟器默认是
FullStateSimulator，但若代码里显式用了ResourceEstimator而没装对应包，也会失败——查csproj是否含<PackageReference Include="Microsoft.Quantum.ResourceEstimator" Version="..." />
最易被忽略的是：Q# 不是解释型语言，所有 .qs 文件必须经编译生成 QIR（Quantum Intermediate Representation）才能被模拟器加载。这个过程完全静默，只有当宿主程序调用失败时才暴露问题——所以每次改完 .qs，务必确保 dotnet run 重新触发完整构建链。
