部署一个静态网站，理论上是最简单的运维操作。HTML、CSS、JS 丢到一个静态托管服务上，配个域名，完事。但真实情况是你得处理的杂事远比想象中多：
路由配置（SPA fallback 规则） API 代理（跨域和转发） 认证策略（角色鉴权） 环境变量（多环境管理） 构建产物路径（不同框架输出目录不一样） PR 预览环境（分支自动部署和销毁）
这些事单独做都不难，拼在一起就是一片沼泽。
Azure Static Web Apps 本身就是为了填这个坑而生的，它把前端托管和 serverless API 作为基石，上面叠了认证授权和 CDN 分发。但它的 CLI 工具 swa 有一个问题：参数太多，第一次上手不知道该从哪开始。Smithery 上这个 azure-static-web-apps Skill 做的事情很简单，把这套 CLI 里最常用的五步操作路径封装成一个可复用的指令模板，让 AI Agent 能直接帮你跑部署流程。
这跟那种”我给你一段 Bash 脚本你自己看着改”的方案不一样。这个 Skill 真正有价值的地方，是它把 swa init 这个自动检测框架的机制放在了最高优先级，而且明确禁止手写 swa-cli.config.json。这个约束看起来只是文档里的一句话，实际用起来会发现它避免了大量配置错误。
读完这篇文章，你会知道怎么用这个 Skill 从零搭一个带 API 后端的静态站，配置好 GitHub Actions 自动部署，而且在本地就能完整模拟 Azure 生产环境，全程不需要打开 Azure Portal。
环境准备
前置条件不复杂。你需要 Node.js 18 以上、一个 Azure 账号、以及一个已经初始化好的前端项目。不管你用的是哪种前端框架，SWA CLI 都能自动识别。
安装本身只有一行命令，把 SWA CLI 装成项目开发依赖：
npm install -D @azure/static-web-apps-cli
装完之后跑个版本号确认环境就绪：
npx swa --version
这里有一个新手最容易踩的坑，我在第一次用的时候也翻了车。swa-cli.config.json 这个文件是 swa init 自动生成的，绝对不能手写。它的内容看起来跟一个普通的 JSON 配置文件没什么区别，但 swa init 在生成时做了框架检测、端口探测、构建命令推断这些自动逻辑，手写的配置缺少这些上下文，十有八九会在 swa start 的时候报一些莫名其妙的错误。Skill 文档里把这条规则放在了最显眼的位置，不是没道理的。
操作流程
完整的使用流程分成五个步骤：
-
swa init，初始化配置 -
swa build，构建项目 -
swa start，本地模拟 -
swa login，Azure 认证 -
swa deploy，部署上线
每一步都有对应的 SWA CLI 子命令，Skill 的作用是确保它们按正确的顺序串起来。
swa init 是必须的第一个动作。它会扫描你项目里的配置文件，自动推断出前端框架类型和开发服务器端口，以及构建输出目录和 API 目录的路径。支持的配置文件包括 package.json、vite.config.ts、next.config.js 等，然后把结果写进 swa-cli.config.json。如果你想跳过交互直接接受默认值，加 --yes 就行。
npx swa init --yes
初始化完成后，swa build 会根据检测到的构建命令编译前端代码，swa start 会在 http://localhost:4280 启动一个本地模拟器。这个模拟器不只是简单托管静态文件，它同时启动了 API 代理和认证模拟，你在本地就能完整测试生产环境的所有功能。
npm run build
npx swa start
本地验证通过后，连接 Azure 部署只需要两步。swa login 做身份认证，swa deploy 把构建产物推送到 Azure。如果你想跳过交互式登录，可以用 --deployment-token 传入部署令牌。拿到令牌的方式有两种：Azure Portal 里找到对应 Static Web App 资源的 Overview 页面手动获取，或者直接用 swa deploy --print-token 让 CLI 帮你打印。
npx swa login
npx swa deploy --env production
如果你希望每次推送代码后自动部署，SWA CLI 本身不负责 CI 配置，但 Skill 里给了一套标准的 GitHub Actions workflow 模板。核心是用 Azure/static-web-apps-deploy@v1 这个 Action，配好 app_location、api_location、output_location 三个路径，再加一个 repository secret 存部署令牌。PR 分支自动创建预览环境，合并后自动销毁，整套逻辑跟 Vercel 的预览部署体验类似。
关键设计
这个 Skill 设计上最值得琢磨的点，是它对”配置来源”的态度。很多 DevOps 工具让你手写所有配置，然后给一个校验命令来检查写得对不对。SWA CLI 反过来：它用 init 自动生成配置，你只需要在生成结果上做微调。这个思路的区别在于，前者把认知负担推给了用户，后者把框架知识内建到了工具里。
staticwebapp.config.json 是另一个值得细看的文件。它负责运行时行为，跟构建配置完全解耦。你可以在这里做四件事：
-
定义路由规则 -
配置认证角色 -
设置 API 运行时版本 -
指定导航回退策略
这种配置分离的设计让构建阶段和运行阶段互不干扰，改路由规则不需要重新构建整个项目。
{
"navigationFallback": {
"rewrite": "/index.html",
"exclude": ["/images/*", "/css/*"]
},
"routes": [
{ "route": "/api/*", "allowedRoles": ["authenticated"] }
],
"platform": {
"apiRuntime": "node:20"
}
}
本地模拟器的 API 代理是另一个容易被低估的设计。swa start 启动后，所有 /api/* 请求会被自动转发到本地的 Azure Functions 运行时，不需要你在前端代码里写任何环境判断或代理配置。更实用的是认证模拟：访问 /.auth/login/github 会跳到一个假的登录页面，你可以输入任意用户名和角色来测试不同权限场景。这种本地完全复现生产环境的能力，在同类工具里并不多见。
API 后端的集成方式也值得提一句。Skill 内置了一套 Azure Functions V4 编程模型的模板，创建一个带 HTTP 触发器的函数只要三步：
-
初始化 Functions 项目 -
用 func new生成模板 -
在 staticwebapp.config.json里声明apiRuntime
支持的运行时不止 Node.js，dotnet 8.0、Python 3.10 和 3.11 也都在支持列表里。
使用场景
最常见的用法是给一个纯前端项目加自动部署。假设你有一个 Vite + React 的项目已经托管在 GitHub 上，把这个 Skill 丢给 AI Agent，它能自动跑完初始化、构建、部署全流程，并且在 GitHub 仓库里创建好 CI workflow。整个过程比你手动操作快得多：
-
打开 Azure Portal -
创建 SWA 资源 -
配置构建参数 -
复制部署令牌。
带 API 后端的场景是这个 Skill 真正的发力点。假设你要做一个简单的留言板应用，前端用 React，后端用 Azure Functions 处理留言提交和查询。Skill 会自动检测到 api 目录，在 config 里配置好 apiLocation，本地 swa start 的时候前端和 API 一起跑，不需要分别开两个终端。
swa db init 还有一个比较少被提到的能力：数据库连接初始化。如果你的应用需要连 Cosmos DB 或 Azure SQL，这个命令会自动生成数据库连接配置和 REST API 端点。不过这个功能目前还比较早期，支持的数据库类型只有 mssql、postgresql 和 cosmosdb_nosql 三种。如果你的项目用的是 MySQL 或 MongoDB Atlas，这部分还是得手写。
不是所有项目都适合用这个方案。如果你的前端和 API 是分开部署的，或者你已经在用 Kubernetes 管理所有服务，SWA 的”前端+API 一体化”模式反而会限制你的灵活性。这个 Skill 最适合的场景是中小型项目，团队规模在几个人以内，你不想花时间折腾基础设施，但又需要 API 后端和自动部署。
洞察与反思
用了几次之后，最让我意外的是本地模拟器的完成度。大部分云服务的本地模拟器都很鸡肋，能跑起来就算赢，细节上到处是坑。SWA CLI 的模拟器不仅完整实现了 API 代理和认证模拟，连 staticwebapp.config.json 里的路由规则也能在本地生效。这种程度的本地还原意味着你在开发阶段就能发现大部分配置问题，不用等到部署之后对着 404 页面排查。
跟 Vercel 和 Netlify 比起来，SWA 的定位有明显差异。Vercel 的优势是极致简单，适合纯前端项目；Netlify 的卖点是插件生态和表单处理；Azure SWA 的核心竞争力在”企业级集成”。如果你的公司已经在用 Azure 生态，Active Directory 认证、Key Vault 密钥管理、Application Insights 监控这些服务跟 SWA 的集成几乎是零配置的。反过来，如果你不在 Azure 生态里，这个优势就完全不存在了。
这个 Skill 有一个明显的限制：它的能力边界完全由 SWA CLI 决定。SWA CLI 目前还不支持多区域部署配置、自定义 CDN 规则、A/B 测试等功能，这些需求你还是得去 Azure Portal 手动操作。Skill 本身也没有做任何”超越 CLI 能力”的扩展，它更像是一个精准的 CLI 操作手册，而不是一个替代 Azure Portal 的管理面板。
什么情况下你应该用它？如果你的项目符合这三个特征：前端框架已经在 SWA CLI 的支持列表里、需要 serverless API 后端、愿意把部署流程交给 GitHub Actions，那这个 Skill 能帮你省掉大量的配置时间。如果你需要的是高度定制化的部署流水线，或者你的架构本身就不是”前端+API”的一体化模式，那 SWA CLI 加上这个 Skill 也帮不了你。
资源地址
| 资源 | 链接 |
|---|---|
| Smithery 页面 | https://smithery.ai/skills/github/azure-static-web-apps |
| Azure Static Web Apps 文档 | https://learn.microsoft.com/azure/static-web-apps |
| SWA CLI GitHub | https://github.com/Azure/static-web-apps-cli |
| Azure Functions 文档 | https://learn.microsoft.com/azure/azure-functions |
总结
Azure Static Web Apps Skill 的核心价值在于把一套其实不难、但很容易出错的部署流程，变成了一条可靠的指令链。它不试图替代 Azure Portal，也不想做 Vercel 的竞品。它就是老老实实地把 SWA CLI 最常用的五个步骤固化成 Skill 指令，然后加了一套足够详尽的故障排查指南。
如果你刚好在 Azure 生态里做中小型项目，这个 Skill 值得一试。哪怕你不打算让 AI Agent 帮你跑完整部署流程，把 Skill 当成 SWA CLI 的交互式速查手册来用，也比翻微软文档快得多。
如果你还没用过 Azure Static Web Apps，建议先从 SWA CLI 的本地模拟器开始体验，不需要 Azure 账号也能跑 swa start。本地跑顺了，再考虑要不要推到云端。