问题：代码写完了，但真的能部署到 Azure 吗？
你花了数周甚至数月开发一个应用。代码在本地运行正常，团队很有信心，准备部署到 Azure 开始服务用户。
于是你开始配置基础设施——编写 Bicep 模板、设置 Azure App Service、配置容器注册表。你运行 azd up 或推送到 CI/CD 流水线。然后……失败了。
也许构建失败了，因为某个依赖与你选择的运行时不兼容。也许你的应用依赖一个本地服务（比如基于文件的数据库），而云环境中并不存在。也许你发现所使用的框架版本不被目标 Azure 服务支持。或者你在中途意识到需要一个 Dockerfile，但之前没人想到要创建。
这些都不是假设场景。它们在实际部署中频繁发生。根本原因几乎总是相同的：团队在验证源代码是否真正可部署之前，就急于进行基础设施规划。
为什么会出现这种情况
"本地能跑的代码"和"能部署到云平台的代码"之间的差距，比大多数开发者预期的要大。原因如下：
- 本地环境过于宽容。 你的机器上有全局安装的包、环境变量、本地数据库和文件系统访问权限，这些在云环境中都不存在。
- 依赖假设是隐式的。 你的
package.json或requirements.txt可能列出了依赖，但没有说明这些依赖是否与目标运行时或架构兼容。 - 配置分散各处。 连接字符串、环境变量和服务绑定经常被硬编码，或者被假设存在而没有显式声明。
- 框架支持有差异。 Azure 支持很多框架，但并非每个框架的每个版本都能在每个服务上运行。Node.js 14 的应用无法在要求 Node.js 18+ 的服务上运行。
- 没人提前检查。 典型的工作流程是：写代码 → 写基础设施 → 部署 → 失败 → 调试。失败发生在最昂贵的阶段。
一个好的解决方案应该改变什么
正确的预部署评估应该在任何基础设施工作开始之前进行。它应该：
- 静态扫描代码仓库 —— 不安装依赖、不运行构建 —— 识别应用包含什么。
- 检测技术栈 —— 框架、语言、运行时 —— 并验证与 Azure 服务的兼容性。
- 检查构建健康度 —— 是否有构建脚本、清单文件和配置表明这是一个可构建的项目？
- 评估完整性 —— 应用是否拥有部署所需的文件（如 Dockerfile、入口点、配置文件）？
- 识别阻碍因素 —— 不受支持的框架、不兼容的依赖、缺失的配置，或对仅限本地服务的依赖。
- 生成可操作的判定结果 —— 不仅仅是"通过/失败"，而是具体的建议：需要改什么、缺什么、什么阻碍了部署。
目标是将失败点左移——从基础设施部署阶段移回到代码评估阶段，在那里修复成本低且速度快。
介绍 azure-app-onboard-prereq：部署前的代码就绪检查
解决这个问题的一个选项是 azure-app-onboard-prereq 技能。它旨在在你编写任何基础设施代码之前，评估源代码仓库的 Azure 部署就绪状态。
这个技能是微软 azure-skills 仓库中更大的 AppOnboard 流水线的一部分，但也可以独立使用。它的目的很明确：扫描你的仓库，评估其中的内容，告诉你应用是否准备好部署——如果没有，是什么在阻碍它。
它实际做了什么
该技能对你的仓库执行多维度评估：
- 构建健康度检查： 你的项目是否有构建所需的清单文件（如
package.json、pom.xml、go.mod、Cargo.toml）？是否定义了构建脚本？是否有 Dockerfile 或等效文件？ - 完整性检查： 应用是否有入口点、配置文件和可部署应用所需的最低结构？
- 可部署性检查： 检测到的框架和运行时是否与 Azure 服务兼容？是否有会导致部署失败的依赖？是否有仅限本地的服务（如 SQLite 文件数据库或 localhost URL）在云中无法工作？
- 依赖兼容性： 你的依赖与 Azure 目标环境之间是否存在已知的不兼容问题？
输出是一组按组件的判定结果——PASS、WARN 或 FAIL——附带具体说明和建议修复方案。
一个关键设计决策：只读评估
该技能的一个重要特性是：在评估阶段严格只读。它不会安装依赖、运行构建或执行测试。这是一个刻意的设计选择：
- 保持评估快速且安全——不会修改你的环境。
- 避免运行任意构建命令带来的副作用风险。
- 可在任何仓库上工作，无需本地运行环境。
相反，该技能执行静态分析：读取清单文件、检查配置模式、从依赖声明中检测框架版本，并与已知的 Azure 兼容性数据进行比对。
这意味着即使你本地没有安装运行时，它也能评估仓库。同时也意味着它不会捕获运行时错误——它检查的是结构就绪性，而非功能正确性。
该技能适用的场景（以及不适用的场景）
适用场景
- 在开始基础设施工作之前。 你有一个可运行的应用，想在编写 Bicep、Terraform 或 ARM 模板之前确认它是否准备好部署到 Azure。
- 评估新仓库。 你接手或 fork 了一个项目，需要了解其部署就绪状态。
- 部署前审计。 你的团队希望在发布前进行系统性检查，以发现配置缺口或依赖问题。
- Monorepo 评估。 该技能可以检测单个仓库中的多个组件，并独立评估每个组件。
- 回答"我能把这个部署到 Azure 吗？" 这是该技能明确设计来回答的直接问题。
不适用的场景
该技能的文档清楚地说明了其边界：
| 如果你需要... | 请改用 |
|---|---|
| 验证现有的基础设施代码（Bicep、Terraform、azure.yaml） | azure-validate |
| 生成基础设施即代码 | azure-prepare |
| 运行端到端部署流水线 | azure-app-onboard |
执行 azd up 或部署到 Azure |
azure-deploy |
该技能专门用于第一个阶段——代码就绪检查。如果你已经编写了基础设施代码并需要验证它，这不是合适的工具。
它不会做什么
- 它不会修复你的代码。它识别问题并推荐修复方案，但修复是单独的步骤。
- 它不会运行你的测试。它静态检查测试配置文件，但不执行测试套件。
- 它不会安装包。评估完全基于静态分析。
- 它不会生成部署配置。它告诉你需要什么，但不会替你创建。
评估该技能是否适合你的工作流程
设置上下文
该技能在基于会话的工作流中运行。它创建一个会话目录（.copilot-azure/sessions/{session-id}/）并在其中写入评估产物。它读取你的仓库结构并生成一个 prereq-output.json 文件，包含结构化的发现结果。
它可以通过两种方式调用：
- 作为
azure-app-onboard流水线的一部分 —— 作为更大的入门流程的第 3 步运行。 - 独立使用 —— 你直接调用它进行代码就绪检查。
如果独立调用，它会自动处理会话创建，并通过 az account show 检查是否有活动的 Azure 账户。
安全信号
- 默认只读。 该技能在评估期间不会修改你的代码。唯一的例外是修复阶段，仅在你有阻碍性问题时运行，且即使如此，也需要用户明确同意后才能进行更改。
- 不执行任意命令。 该技能明确禁止在预检查阶段运行
npm install、pip install、dotnet build、pytest或任何其他安装/构建/测试命令。这作为绝对规则在技能配置中强制执行。 - 用户同意门控。 任何代码修改都需要用户确认。该技能在呈现结果之前最多限制为 3 个问题。
- MIT 许可证。 底层仓库使用宽松的开源许可证。
仓库信号
该技能来自 microsoft/azure-skills 仓库：
- 1,328 颗星和 220 个 fork —— 表明有实质性的社区采用。
- 由微软维护 —— 与维护 Azure 本身的组织相同，这意味着兼容性数据和最佳实践可能保持最新。
- 属于结构化流水线 —— 该技能是 4 阶段 AppOnboard 流水线中的一个阶段，表明它在设计时就有明确的范围和集成点。
- 低安全级别 —— 该技能执行静态分析，除了通过 Azure CLI 验证账户外，不需要提升权限或访问外部服务。
使用前需要检查的事项
在采用该技能之前，请考虑：
- 你的技术栈。 该技能检测常见的框架和语言，但请确认你的特定技术栈是否被覆盖。评估通过
mcp_azure_mcp_get_azure_bestpractices引用 Azure 最佳实践来验证检测到的模式。 - Monorepo 复杂度。 如果你的仓库有很多组件，该技能可以处理，但你可能需要根据你的具体结构审查组件映射逻辑。
- 云 SDK 依赖。 如果你的应用使用 AWS SDK、Google Cloud SDK 或 Firebase，该技能会在早期标记这一点，并提供重定向到云迁移技能的选项。如果你在评估多云应用，请注意这个行为。
- 与 CI/CD 的集成。 该技能生成结构化的 JSON 输出（
prereq-output.json），可以被下游工具消费，但你需要将其接入你的流水线才能实现自动化的部署前检查。 - 修复预期。 该技能识别问题，但修复遵循单独的修复协议。如果你期望自动修复，请理解这需要额外的步骤和用户同意。
实际示例：评估结果是什么样的
假设你有一个 Node.js Express 应用，结构如下：
my-app/
├── package.json
├── src/
│ └── index.js
├── .env
└── data/
└── local.db
该技能可能会生成以下发现：
- PASS：
package.json存在，包含有效的依赖和启动脚本。 - WARN： 检测到
.env文件——环境变量需要在 Azure App Settings 或 Key Vault 中配置。 - FAIL：
data/local.db表明使用了本地 SQLite 数据库——这在 Azure App Service 中不会持久化。你需要迁移到 Azure SQL、Cosmos DB 或其他托管数据库服务。 - WARN： 未检测到 Dockerfile——如果你计划使用基于容器的部署，需要创建一个。
- PASS：
engines字段中的 Node.js 版本与 Azure App Service 支持的运行时兼容。
这些判定结果让你清楚地了解在投入时间做基础设施之前需要改变什么。
总结
"本地能跑"和"能部署到 Azure"之间的差距是常见的浪费时间和挫败感的来源。azure-app-onboard-prereq 技能提供了一种结构化的、只读的仓库评估方式，在你开始基础设施工作之前识别部署阻碍。
它不是一个通用解决方案——它专门设计用于部署前的代码就绪阶段。它不会验证基础设施、生成部署配置或自动修复你的代码。但如果你正处于"我的应用准备好部署到 Azure 了吗？"或"什么在阻碍我的部署？"这样的阶段，它提供了一种系统性的方式来回答这些问题。
根据你的特定技术栈来评估它，理解其只读设计，并在采用之前检查其输出格式是否与你的工作流程集成。