Azure Static Web Apps CLI swa start完全教程静态托管、连接Dev Server与自动启动开发服务器【免费下载链接】static-web-apps-cliAzure Static Web Apps CLI ✨项目地址: https://gitcode.com/gh_mirrors/st/static-web-apps-cliSWA CLIAzure Static Web Apps CLI简称 swa CLI是 Azure Static Web Apps 的官方本地开发工具核心命令swa start可在本地一键启动模拟器既能直接托管静态网页也能反向代理你的前端 Dev Server还能自动拉起后端 API 与模拟登录认证。本教程带你从零跑通这三种最常见的本地开发模式。一、swa start 能做什么swa start 本质上是在你本机启动一个迷你版 Azure Static Web Apps。它默认监听http://localhost:4280把浏览器发来的请求智能分流静态资源请求→ 交给静态文件服务器或转发给你的前端 Dev Server热更新不断认证请求→ 交给本地认证/授权模拟器可模拟 GitHub、Google 等身份源登录API 请求→ 交给 Azure Functions Core Tools 运行时或转发到你手动启动的 API 服务。这张架构图位于 docs/swa-cli-architecture.png展示了 swa start 在 4280 端口上同时托管静态内容、认证模拟和 Functions 运行时的全貌。请求处理的核心逻辑实现在 src/msha/server.ts命令入口在 src/cli/commands/start/start.ts。二、快速安装 swa CLI只需一条 npm 命令即可全局安装项目内开发建议加-D作为开发依赖npm install -g azure/static-web-apps-cli安装完成后进入你的项目根目录注意要位于项目根而不是/api或/app子目录内cd my-awesome-swa-app swa --version三、模式一静态托管——从一个文件夹直接启动最简单的用法当前目录就是构建产物时直接运行swa start如果你的构建产物在别的目录比如dist、build把路径作为第一个参数传入即可swa start ./my-dist这就是纯静态托管模式swa start 会读取目录里的index.html等文件并提供服务同时自动识别目录中的staticwebapp.config.json来模拟云端的路由重写、自定义 404 页面等配置配置说明见 docs/www/docs/cli/swa-start.md。小贴士如果构建产物目录和源码目录不同也可以在项目根目录的swa-cli.config.json中把outputLocation固定下来以后直接swa start即可参考示例见 docs/swa-cli.config.json。四、模式二连接 Dev Server——保留热更新的最佳姿势正式开发前端时你不会只想看静态文件还需要框架自带的热更新HMR和实时重载。swa start 支持反向代理到你框架的开发服务器方法分两步像平常一样启动你的 Dev Server如npm start、ng serve记下它的地址另开一个终端把这个地址传给 swa startswa start http://localhost:3000之后浏览器统一访问http://localhost:4280页面内容实际来自 3000 端口的 Dev Server而认证、API 等云服务能力由 swa CLI 提供——鱼和熊掌兼得。上图就是 Svelte 项目经 Dev Server 由 swa start 代理后的页面效果测试用例位于 e2e/samples/app/svelte-kit/。常见框架 Dev Server 默认端口速查框架默认端口启动命令React / Next.js / Vue (Vite)3000 / 5173swa start http://localhost:3000Angular4200swa start http://localhost:4200Blazor WebAssembly5000swa start http://localhost:5000Hugo1313swa start http://localhost:1313Gatsby8000swa start http://localhost:8000Jekyll4000swa start http://localhost:4000五、模式三--run 自动启动开发服务器——一条命令搞定不想开两个终端给--run参数一个启动命令swa start 会在内部帮你把 Dev Server 拉起来# Reactnpm start 脚本 swa start http://localhost:3000 --run npm start # Blazor swa start http://localhost:5000 --run dotnet watch run # Jekyll swa start http://localhost:4000 --run jekyll serve # 你自己的启动脚本 swa start http://localhost:4200 --run ./startup.sh--run的底层实现是 src/cli/commands/start/start.ts 中的启动脚本封装支持任意 shell 命令和脚本文件。你也可以把devServerUrl和run写进swa-cli.config.json让团队共享同一套启动配置。⏱️ 如果 Dev Server 启动较慢可用-t, --devserver-timeout延长等待时间默认 60 秒例如swa start http://localhost:3000 -t 120。六、前后端一起跑API 与本地认证的模拟自动启动 API 服务器如果项目里带了 Azure Functions 风格的api目录用--api-location指定它# 静态目录 API swa start ./my-dist --api-location ./api # Dev Server API swa start http://localhost:3000 --api-location ./apiswa CLI 会自动检查Azure Functions Core Tools是否已安装没有的话会替你下载对应版本并启动API 默认监听 7071 端口可用-j, --api-port修改。手动连接已启动的 API如果你习惯在 VS Code 里调试 Functions先func host start再起 swa 即可swa start ./my-dist --api-devserver-url http://localhost:7071本地模拟登录认证swa start 还会在浏览器里提供一套认证模拟页见下图可以手动设定 Provider、User ID、角色和 Claims快速验证登录前后页面不一样的权限逻辑无需真实账号上图是一个 Hugo 静态站点经 swa start 托管后的渲染效果对应样例位于 e2e/samples/app/hugo/。七、常用参数速查清单参数作用默认值./my-dist位置参数静态产物目录或 Dev Server URL.-O, --output-location构建产物目录相对--app-location.-i, --api-locationAPI 项目目录--D, --app-devserver-url前端 Dev Server 地址--is, --api-devserver-urlAPI Dev Server 地址--r, --run启动时执行的自定义命令--p, --port模拟器端口4280-q, --host监听地址localhost-o, --open启动后自动打开浏览器false-s, --ssl使用 HTTPS 提供服务false-w, --swa-config-locationstaticwebapp.config.json所在目录--t, --devserver-timeout等待 Dev Server 就绪的秒数60 任何参数都可以用swa start --help随时查看若 4280 端口被占用CLI 会提示你换一个可用端口也可以用-p主动指定。八、新手常见问题Q1swa start和swa start http://localhost:3000有什么区别前者只托管静态文件改了要重新构建后者把页面请求代理给 Dev Server保留热更新日常开发推荐后者。Q2访问 4280 端口一直转圈怎么办确认 Dev Server 已真正监听该地址启动慢的项目加-t 120仍不行就加--verbose查看详细日志定位问题。Q3本地和线上行为不一致swa CLI 模拟的是 Azure 常用能力边界情况可能有差异——文档 readme.md 中明确提示上线前务必部署到 Azure 做最终验证。Q4能指定 SSL 证书做 HTTPS 开发吗可以swa start http://localhost:3000 -s -e ./cert.crt -k ./cert.key。写在最后掌握swa start的三种姿势——静态托管、连接 Dev Server、--run 自动拉起——基本就覆盖了 90% 的本地开发场景。配合--api-location与本地认证模拟你可以在一个端口里同时调试前端、API 和登录逻辑体验与云端高度一致的完整链路。更多细节可参阅仓库内的 docs/www/docs/cli/swa-start.md 与 docs/www/docs/use/2-emulator.md。【免费下载链接】static-web-apps-cliAzure Static Web Apps CLI ✨项目地址: https://gitcode.com/gh_mirrors/st/static-web-apps-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考