“使用 Google 账号登录”按钮（网页版）

“使用 Google 账号登录”按钮（网页版）

关于此 Codelab

subject上次更新时间：4月 28, 2025
account_circleBrian Daugherty 编写

1. 概览

在此 Codelab 中，我们将构建一个用于用户登录的简单网页。您将使用 Google Identity 服务 JavaScript 库来显示和自定义“使用 Google 账号登录”按钮。

“使用 Google 账号登录”按钮。

学习内容

  • 如何向网页添加“使用 Google 账号登录”按钮
  • 如何设置 OAuth 2.0 Web 应用
  • 如何解码 ID 令牌
  • 如何自定义“使用 Google 账号登录”按钮

所需条件

  1. 一个文本编辑器和用于托管网页的环境，我们将在此 Codelab 中介绍以下环境：
    • 在机器的终端本地运行，或者
    • Glitch 等平台编写代码。
    选择您最满意的环境。
  2. Google Cloud 项目。您可以使用现有项目，也可以创建一个新项目。Google Cloud Platform 账号和项目是免费的。
  3. 具备 HTML、CSS、JavaScript 和 Chrome 开发者工具（或同等课程）的基础知识。

下面我们开始步入正题

2. 创建登录页面

接下来，将此代码示例添加到名为 index.html 的文件中。您可以在计算机上使用自己喜欢的文本编辑器或在 Glitch 等平台上执行此操作。

<!DOCTYPE html>
<html lang="en">
  <head>
    <script src="https://accounts.google.com/gsi/client" async></script>

    <script>
      function decodeJWT(token) {

        let base64Url = token.split(".")[1];
        let base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
        let jsonPayload = decodeURIComponent(
          atob(base64)
            .split("")
            .map(function (c) {
              return "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2);
            })
            .join("")
        );
        return JSON.parse(jsonPayload);
      }

      function handleCredentialResponse(response) {

        console.log("Encoded JWT ID token: " + response.credential);

        const responsePayload = decodeJWT(response.credential);

        console.log("Decoded JWT ID token fields:");
        console.log("  Full Name: " + responsePayload.name);
        console.log("  Given Name: " + responsePayload.given_name);
        console.log("  Family Name: " + responsePayload.family_name);
        console.log("  Unique ID: " + responsePayload.sub);
        console.log("  Profile image URL: " + responsePayload.picture);
        console.log("  Email: " + responsePayload.email);
      }
    </script>
  </head>
  <body>
    <!-- g_id_onload contains Google Identity Services settings -->
    <div
      id="g_id_onload"
      data-auto_prompt="false"
      data-callback="handleCredentialResponse"
      data-client_id="PUT_YOUR_WEB_CLIENT_ID_HERE"
    ></div>
    <!-- g_id_signin places the button on a page and supports customization -->
    <div class="g_id_signin"></div>
  </body>
</html>

此代码混合了 HTML 和 JavaScript，可以执行多种操作：

  • 使用 g_id_onload 配置此 Google Identity 服务库，
  • 会显示使用 g_id_signin 的“使用 Google 账号登录”按钮，
  • 添加一个名为 handleCredentialResponse 的 JavaScript 回调函数处理程序，用于从 Google 接收用户登录凭据；以及
  • decodeJWT 函数，用于将 JSON 网络令牌 (JWT) 凭据转换为纯 JSON。

data-client_id="PUT_YOUR_WEB_CLIENT_ID_HERE" 看起来有些不太正常。

我们先不予理会，待会儿再回来看看。

3. 提供您的网页

我们将讨论两种用于向浏览器提供 index.html 的环境：

  • 在机器本地运行网络服务器
  • 比如 Glitch 这样的远程平台。

请选择您最舒服的方式。设置完成后，我们将使用该网址配置 OAuth Web 客户端。

从机器本地

确保您的系统上安装了 Python3。设置因操作系统和平台而异。如果您需要在机器上安装 Python，请先从 Python 设置和使用开始。

在包含 index.html 的目录中启动 Python Web 服务器：

$ python3 -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

现在，网络服务器正在监听端口 8000 上的连接，并已准备好提供您的登录页面。网址为

http://localhost:8000

使用远程平台

如果您已选择使用 Glitch（或等效功能）修改和托管登录页面，则应该能够在预览窗格或新的浏览器标签页中打开 index.html。

通常，您使用的网址就是您在设置 glich.com 项目时输入的项目名称。例如，如果您的故障项目名称为 gis-example，则网址为 https://gis-example.glitch.me。当然，您将选择其他项目名称，并且无法重复使用该名称。网址为

https://<var>your-project-name</var>.glitch.me

加载网页

请稍候...

我们首先创建一个 OAuth 2.0 Web 客户端并对其进行配置。

复制或记下该网址，下一步会用到该网址。

4. 设置 OAuth Web 客户端

我们来配置 OAuth，以便用户能够实际登录。

  • 点击此链接创建 OAuth 2.0 Web 客户端。如有需要，向导会帮助您创建和设置新的 Google Cloud 项目。
  • 从应用类型下拉列表中选择 Web 应用。
  • 按已获授权的 JavaScript 来源下的添加 URI 按钮
  • 输入第 3 步 提供您的网页中所述的托管 index.html 的网址。

    托管在本地机器上

    您机器上托管的本地源

    托管在远程平台上

    使用远程托管平台
  • 按创建
  • 复制新的客户端 ID。

最后一项操作

我们需要返回并更新 index.html 以使用新的客户端 ID。在您的编辑器中，将 PUT_YOUR_WEB_CLIENT_ID_HERE 替换为您的新客户端 ID。客户端 ID 如以下示例所示：1234567890-abc123def456.apps.googleusercontent.com。

登录！

5. 登录

首先，打开浏览器的开发者控制台，所有错误和从 Google 返回的 JWT ID 令牌凭据都将记录在此处。

按下“使用 Google 账号登录”按钮！

接下来的情况可能会有所不同：

  • 如果您目前已登录多个 Google 账号，系统会提示您选择用于登录此 Web 应用的账号。
  • 如果这是您首次登录此 Web 应用，系统会显示意见征求提示。

在选择性地选择账号并表示同意后，Google 随后会提供一个 JWT 进行响应。在浏览器中运行的 handleCredentialResponse 回调函数接收 JWT。

在此 Codelab 中，我们将解码并输出 JWT 内容。在正式版 Web 应用中，您将验证并使用已解码的 JWT 执行更有意义的操作，例如在后端平台上创建新账号或为用户建立新会话。

6. 检查 JWT ID 令牌

系统会将编码的 JWT 记录在开发者控制台中。解码 JWT 后，控制台也会记录一些常用的 ID 令牌字段。

您可以使用 jwt.io 等在线工具解码 JWT。

或者，您也可以使用终端中的 jq 解码和查看 JWT（您可能需要使用软件包管理器来安装 jq）。首先，将编码的 JWT 字符串粘贴到双引号中：

$ JWT="eyJhbGciOiJSUzI1Ni ... Hecz6Wm4Q"

然后使用此命令将其解码为

$ echo $JWT | jq -R 'split(".") | .[0],.[1] | @base64d | fromjson'
{
  "alg": "RS256",
  "kid": "c7e04465649ffa606557650c7e65f0a87ae00fe8",
  "typ": "JWT"
}
{
  "iss": "https://accounts.google.com",
  "azp": "123456789012-s0meRand0mStR1nG.apps.googleusercontent.com",
  "aud": "123456789012-s0meRand0mStR1nG.apps.googleusercontent.com",
  "sub": "2718281828459045",
  "email": "example@example.com",
  "email_verified": true,
  "nbf": 1744645148,
  "name": "Brian Daugherty",
  "picture": "https://lh3.googleusercontent.com/a/08a898b88ca4d6407be652d8",
  "given_name": "Brian",
  "family_name": "Daugherty",
  "iat": 1744645448,
  "exp": 1744649048,
  "jti": "52cd32984b30e178aa88bc2e75e63e055a461fcf"
}

电子邮件、姓名和图片等一些键和值应该很容易理解。其他值用于在您使用 JWT 之前对其进行验证。通过 ID 令牌获取用户信息详细介绍了所有字段的含义。

7. 自定义按钮

在网页上放置默认登录按钮的操作方法如下所示

    <div class="g_id_signin"></div>

您会看到这个按钮

“使用 Google 账号登录”按钮。

但您可能需要更改颜色、大小或文字，使其与您网站的主题保持一致。

接下来，我们将按钮颜色更改为蓝色，改为使用 Google 注册。

打开 index.html，找到 g_id_signin 元素，然后添加 data-theme="filled_blue" 和 data-text="signup_with" 属性：

    <div
      class="g_id_signin"
      data-theme="filled_blue"
      data-text="signup_with"
    ></div>

保存并重新加载页面后，您会看到一个包含新文本的蓝色按钮。

“使用 Google 注册”按钮。

您可以进一步自定义该按钮，如需查看完整的选项列表，请参阅可视化数据属性。

8. 其他资源

恭喜！

您已向网页添加了“使用 Google 账号登录”按钮，配置了 OAuth 2.0 Web 客户端，已解码 JWT ID 令牌，还学习了如何自定义该按钮的外观。

以下链接可能有助于您完成后续步骤：

常见问题解答

bug_report 报告错误