自定义登录页

云开发在每个环境的静态托管里预置了一个登录页。平台可以直接改造它——换品牌、改文案、调配色、决定展示哪些登录方式。

改造的是登录页的配置文件和图片资源，不涉及身份认证的登录配置。改完覆盖回静态托管，几秒内生效。

适用于需要统一品牌形象，或要把登录页嵌进自有产品页面的平台。

登录页的组成

路径	说明
`__auth/index.html`	壳页面，约 0.5 KB。加载 SSO 的远程渲染器，页面内容由渲染器按配置生成
`__auth/env/login.config.json`	登录页配置。品牌、配色、登录方式、协议、登录策略都在这里
`__auth/env/<hash>.png`	logo 图片，由配置里的 `logo` 字段引用
`__auth/env/agreement/<hash>`	协议正文，由配置里的 `agreement.path` 字段引用

访问地址是 https://<环境域名>/__auth。__auth 是身份认证 SSO（单点登录）的固定路径，环境创建时写入。

改造通常只动 __auth/env/ 下的文件：配置、logo，以及需要改协议正文时的协议文件。壳页面不需要改。

⚠️ 不要删除 __auth 下的文件。删除后 /__auth 返回 404，登录流程中断。误删可在 SSO 恢复页面恢复预置登录页。

配置项

login.config.json 里需要关注的字段：

字段	类型	说明
`logo`	String	logo 图片路径，通常写 `/__auth/env/<hash>.png`
`backgroundColor`	String	页面背景色，十六进制色值
`miniprogram`	Array	小程序端登录方式。每项含 `id`、`label`、`type`、`enable`
`web`	Array	Web 端登录方式。每项含 `id`、`label`、`type`、`icon`、`enable`，`extraLink` 可配一个辅助链接
`agreement`	Object	协议勾选项。`items` 里分别是隐私协议和用户协议的 `label`、`type`、`value`、`enable`；`path` 指向协议正文文件
`userRegistry`	Object	是否允许用户自助注册
`access`	Object	登录策略。`needLogin` 控制是否强制登录，`noPermissionPolicy` 控制无权限时的行为，`defaultRoleId` 指定默认角色

items[].value 是勾选项对应的标识，协议正文不在这里，而在 agreement.path 指向的文件里。path 的值是相对环境域名的路径，例如 __auth/env/agreement/c3887e49bb82439bf2f0d21adac1f4b8。

示例里还会出现 name、keepRedirectUri、showDoc、loginPage、security，以及 access 下的 type、maxDevice。这些由平台在保存配置时写入，一般保持原值，不需要改。

改造前先备份原文件，回滚时替换回来即可。一份完整配置：

{
  "logo": "/__auth/env/54423064ef3ba6c1176a6a07b110cc26.png",
  "name": "",
  "backgroundColor": "#f3f3f3",
  "web": [
    {
      "id": "__password",
      "label": "账户密码登录",
      "type": "password",
      "enable": true,
      "extraLink": {
        "title": "忘记账号或密码",
        "url": "https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/extensions/manage-system/faq.html",
        "type": "_blank"
      },
      "icon": "https://cloudcache.tencent-cloud.com/qcloud/ui/static/static_source_business/c0774b3d-2718-46b7-bb21-785e164f1ca0.svg"
    }
  ],
  "keepRedirectUri": true,
  "showDoc": false,
  "miniprogram": [
    {
      "id": "__miniprogram_phone",
      "label": "微信小程序手机号授权",
      "type": "miniprogram_phone",
      "enable": true
    }
  ],
  "agreement": {
    "enable": true,
    "items": [
      { "label": "隐私协议", "type": "privacy", "value": "", "enable": true },
      { "label": "用户协议", "type": "user", "value": "", "enable": true }
    ],
    "path": "__auth/env/agreement/c3887e49bb82439bf2f0d21adac1f4b8"
  },
  "userRegistry": { "enable": false },
  "access": {
    "needLogin": true,
    "noPermissionPolicy": "to_login",
    "whiteListPageIds": "",
    "configVersion": "v2",
    "type": "env",
    "maxDevice": 1
  },
  "security": { "expiresTime": 2592000, "enableLoginStatusShare": true },
  "loginPage": "env"
}

配置里 type 的取值要与控制台中已开通的登录方式对应。改配置只影响界面展示，不改变登录方式的开关，开关仍在身份认证的「登录方式」中配置。

改造流程

取现有文件：下载 __auth/env/login.config.json、logo 图片，需要改协议正文时再下载 agreement.path 指向的文件
改造：按上一节的字段说明改配置；换 logo 就替换图片文件，改协议就替换协议正文文件
覆盖上传：把改好的文件按原路径传回静态托管。路径不一致会导致配置或协议读不到
验证：用无痕窗口访问 https://<环境域名>/__auth，确认新页面生效

静态托管没有构建环节，文件上传即发布，不需要额外的部署动作。

上传方式

按你的集成形态选一种：

方式	操作
控制台	静态托管 → 文件管理，进入 `__auth/env/` 上传覆盖
命令行	`tcb hosting deploy ./login.config.json /__auth/env/login.config.json`
COS SDK	用静态托管桶的临时密钥 `PutObject` 到 `__auth/env/login.config.json`

批量改造多个环境时按环境循环执行，每个环境的 __auth 相互独立。

注意事项

事项	说明
缓存	静态托管走 CDN，上传后通常几十秒内生效。验证时换用无痕窗口
协议文件名	`agreement/<hash>` 的文件名由平台生成、每次不同，不要硬编码。改协议走 `agreement.path` 指向的路径
网关路由	HTTP 网关的路由不要使用通配域名（`domain: "*"`），会拦截 `__auth` 路径，登录页打不开
整页替换	壳页面也可以整页替换，但它加载的是远程渲染器，页面内容仍由配置决定。后续平台升级可能覆盖，一般不建议
密钥	登录页是前端代码，配置里不要写入 SecretId、AppSecret 等任何密钥
云应用接口	`DescribeCloudAppCosInfo` 面向云应用（build service），`__auth` 不是云应用服务，不能用来上传登录页

登录页的组成​

配置项​

改造流程​

上传方式​

注意事项​

相关文档​

登录页的组成

配置项

改造流程

上传方式

注意事项

相关文档