如何调试Azure静态Web应用（SWA）中的自定义认证GetRoles API？

算力阿峰

2026-6-28

Azure静态Web应用（SWA）自定义角色分配问题排查方案

一、GetRoles函数不触发的核心排查点

严格匹配函数命名与路径
SWA要求自定义角色函数必须命名为GetRoles，且必须放在API目录的auth子目录下（如api/auth/GetRoles）。函数需为HTTP触发类型，且authLevel设为anonymous（SWA认证服务会主动调用该函数，无需额外权限校验）。
以Node.js为例，检查function.json中的route是否为auth/getroles，authLevel是否配置正确。
本地调试的配置补全
本地调试时需确认：
- 函数已成功启动，终端显示类似Functions: GetRoles: [GET,POST] http://localhost:7071/api/auth/getroles的运行状态
- SWA CLI启动命令swa start ./my-dist --api-devserver-url http://localhost:7071无参数拼写错误，确保API服务已正确关联
- 可手动调用http://localhost:7071/api/auth/getroles，验证函数是否返回预期角色数组，同时查看函数终端日志确认调用记录
部署后的配置验证
部署到Azure后：
- 在SWA资源的「认证」→「自定义角色」页面，确认已开启「使用自定义角色函数」，且函数路径正确指向/api/auth/getroles
- 进入SWA的「API」页面，确认GetRoles函数存在且状态正常；若通过CI/CD部署，需检查脚本未忽略API目录的上传

清除浏览器缓存
登录后角色未更新多因浏览器缓存了旧认证会话，可尝试：
- 使用无痕模式重新登录
- 清除浏览器localStorage及SWA相关认证Cookie
修正函数返回格式
GetRoles函数必须直接返回JSON格式的纯数组，如["admin", "reader"]，不能添加额外包装（如{roles: ["admin"]}）。Node.js正确示例：
```
module.exports = async function (context, req) {
    context.res = {
        status: 200,
        body: ["admin", "reader"]
    };
};
```
格式错误会导致SWA忽略返回值，默认使用authenticated角色。

日志查看方法
- 本地调试：函数运行终端会直接输出请求、返回及错误日志
- 云端部署：在SWA资源的「监视」→「日志流」中查看实时日志；也可进入「API」页面的具体函数，通过「监视」→「日志」查看历史记录
无需单独部署Azure Function
SWA支持两种API部署方式：
- 嵌入式API：将函数放在项目api目录下，与前端代码一同部署，SWA自动托管
- 链接式API：单独部署Azure Function应用后，在SWA配置中关联该应用
  自定义角色函数两种方式均支持，嵌入式更适合常规场景。

内容的提问来源于stack exchange，提问作者noro5