yazi：三栏布局 + 异步架构

界面分三栏：左边是父目录，中间是当前目录，右边是文件预览。移动到哪个文件，右边实时更新预览内容：代码文件语法高亮（靠 bat），图片在 kitty 下直接渲染，普通文本直接显示。

和老牌的 ranger 比：ranger 是 Python 写的，启动稍慢，配置更复杂；yazi 是 Rust + 完全异步 I/O，大目录不会卡顿，插件用 Lua 写，生态也在快速成长。

安装：先确认依赖

yazi 的代码预览、文件搜索功能依赖之前装过的工具：

如果前三篇已经装过 bat/fd/rg，直接装 yazi 就行：

1

brew install yazi

安装完后 ya 命令是插件管理器，yazi 命令启动主程序：

1
2

yazi --version
# Yazi 26.5.6

三分钟上手：核心快捷键

启动：

1

yazi

导航

文件操作

搜索与过滤

其他

kitty 下启用图片内联预览

yazi 支持多种图片协议，在 kitty 终端下效果最好，直接把图片渲染在预览面板里，不需要额外安装 ImageMagick。

kitty 协议是 yazi 的默认优先选项，如果你用的是 kitty，装完即用，不需要额外配置。打开 yazi，导航到任意图片文件，右侧预览面板就会显示图片。

如果图片没有显示，检查 TERM 环境变量：

1
2

echo $TERM
# 应该输出 xterm-kitty

输出是 xterm-kitty 说明 kitty 协议生效。如果不是，可能是在嵌套终端或 tmux 里启动了 yazi，协议传递受阻。

.zshrc 集成：退出时自动 cd

直接运行 yazi 有个问题：退出后，终端还停在进入 yazi 前的目录，而不是你在 yazi 里最后浏览的位置。

用 --cwd-file 参数可以解决，在 ~/.zshrc 里加这个函数：

1
2
3
4
5
6
7
8
9

function y() {
    local tmp="$(mktemp -t "yazi-cwd")"
    yazi "$@" --cwd-file="$tmp"
    #          --cwd-file：退出时把当前目录路径写入指定文件
    if cwd="$(cat -- "$tmp")" && [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
        cd -- "$cwd"
    fi
    rm -f -- "$tmp"
}

之后用 y 命令启动，退出 yazi 时 shell 会自动 cd 到你最后停留的目录。yazi 命令照常可以用，行为不变。

插件安装

yazi 用 ya pkg 命令管理插件，插件托管在 GitHub 上，格式是 用户名/仓库名:插件名。

1
2
3
4
5
6
7
8
9
10
11
12

# 添加插件（写入 package.toml，同时下载）
ya pkg add yazi-rs/plugins:zoom
#          yazi-rs/plugins:zoom：仓库:插件名（一个仓库可以包含多个插件）

# 安装 package.toml 里记录的所有插件（换机器后用）
ya pkg install

# 更新所有插件
ya pkg upgrade

# 列出已安装插件
ya pkg list

装完插件后还需要在 ~/.config/yazi/keymap.toml 里绑定快捷键才能用。

几个实用插件：

zoom 和 toggle-pane 是官方插件仓库里的，直接 ya pack -a 就能装。

常见问题

yazi 和 ranger 的区别是什么，值得换吗？

主要区别在性能和配置方式。ranger 是 Python 写的，大目录（几千个文件）下滚动会有延迟；yazi 是 Rust + 异步 I/O，大目录不卡。配置上，ranger 用 Python 写脚本，yazi 用 Lua 写插件。如果你现在用 ranger 没有痛点，不用急着换；如果有性能问题，或者已经用 kitty 希望图片预览更好，换 yazi 值得试试。

图片预览一直显示不出来怎么办？

按顺序排查：1）确认用的是 kitty 终端，echo $TERM 输出应该是 xterm-kitty；2）如果在 tmux 里，需要在 ~/.tmux.conf 里加以下 3 行，然后重启 tmux：

1
2
3

set -g allow-passthrough on
set -ga update-environment TERM
set -ga update-environment TERM_PROGRAM

3）非 kitty 终端（如 iTerm2、WezTerm）也支持内联图片，yazi 会自动检测，无需额外配置。

y 函数和直接运行 yazi 有什么区别？

y 函数是对 yazi 的包装，核心差别只有一个：退出后是否自动 cd。yazi 退出后目录不变，y 退出后自动跳到你在 yazi 里最后浏览的目录。传参方式一样，y ~/Documents 等同于 yazi ~/Documents，直接在指定目录里打开 yazi。

bat：cat 加上语法高亮和 Git 标注

bat 是 cat 的替代品，核心差别：

• 自动语法高亮（支持上百种语言，通过 syntect 库驱动）
• 显示行号
• Git 集成：在行号旁标注哪些行被修改、新增、删除
• 自动分页（内容超过一屏时调用 pager，不会刷屏）

它也被很多其他工具用作渲染底层——fzf 的文件预览、yazi 的代码预览默认都会调用 bat。

安装

1

brew install bat

常用参数

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 查看文件，自动高亮
bat main.go

# 预览主题效果
bat --list-themes | fzf --preview="bat --theme={} --color=always main.go"
#                  ----|fzf 预览窗口实时切换主题效果

# 只输出第 10-20 行
bat -r 10:20 main.go
#   -r：range，指定行范围

# 纯内容输出（管道给其他命令用）
bat -p config.json | jq '.database'
#   -p：plain，去掉装饰，等同于 cat

替换 cat：alias 设置

在 ~/.zshrc 里加：

1
2

alias cat="bat"
alias catp="bat --plain"  # 需要纯输出时用 catp

主题选择

bat 内置了多个主题，Dracula、Nord、Solarized (dark) 比较常见。把选好的主题写进配置文件，不用每次手动指定：

1
2
3
4
5

# 查看当前配置文件位置
bat --config-file

# 编辑配置文件，加入主题设置
echo '--theme="Dracula"' >> "$(bat --config-file)"

eza：ls 的现代替代品

eza 是 ls 的替代品（从已停止维护的 exa fork 而来），默认输出带颜色，额外功能：

• -l 模式显示 Git 状态（文件有没有被修改、是否未追踪）
• --tree 模式展示目录树，取代单独装 tree 命令
• 配合 Nerd Font 字体可以显示文件类型图标

安装

1

brew install eza

核心用法

1
2
3
4
5
6

eza                    # 等同于 ls，彩色输出
eza -l                 # 长格式，显示权限、大小、修改时间
eza -la                # 包含隐藏文件
eza --tree             # 树形展示当前目录
eza --tree -L 2        # 树形展示，深度限制为 2 层
eza -l --git           # 长格式 + Git 状态列

常用参数

1
2
3
4
5
6
7
8
9
10
11
12
13

# 按文件大小倒序排列
eza -l -s size -r
#      -s：sort，指定排序字段
#             -r：reverse，逆序

# 带图标的树形展示，深度 3 层
eza --tree --icons=always -L 3
#          --icons=always：显示图标（需要 Nerd Font）
#                          -L：level，树的深度

# 查看目录，不递归进子目录
eza -lD
#   -D：只显示目录

alias 配置

在 ~/.zshrc 里加：

1
2
3
4
5

alias ls="eza"
alias ll="eza -l --git"
alias la="eza -la --git"
alias lt="eza --tree -L 2"
alias llt="eza -l --tree -L 2 --git"

glow：终端里渲染 Markdown

glow 把 Markdown 渲染成格式化的终端输出，标题有缩进和颜色，加粗正常显示，代码块有高亮，比直接 cat 看 .md 文件体验好很多。

安装

1

brew install glow

常用参数

1
2
3
4
5
6
7
8
9
10
11
12
13

# 渲染单个文件
glow README.md

# 用分页器打开（可以上下滚动）
glow -p README.md
#    -p：pager，开启分页模式

# 指定换行宽度，适合宽屏
glow -w 100 README.md
#    -w：width，自动换行的列数（设为 0 禁用自动换行）

# 交互式浏览当前目录所有 .md 文件
glow

不加参数直接运行 glow，会列出当前目录里的所有 Markdown 文件供选择，适合快速翻看项目文档。

mdcat：图文混排的 Markdown 渲染

mdcat 和 glow 功能类似，核心区别：在 kitty 终端下支持内联显示图片。Markdown 文档里如果有图片，mdcat 会直接把图片渲染在终端里，而不是显示一个链接。

安装

1

brew install mdcat

用法

1
2
3
4
5
6

# 渲染 Markdown 文件（默认不分页，直接输出）
mdcat README.md

# 开启分页（内容多时可上下滚动）
mdcat --paginate README.md
#     --paginate / -p：启用分页器（类似 less），默认是关闭的

glow vs mdcat 怎么选

两个都装，看纯文字文档用 glow，文档里有图用 mdcat。

bat 作为底层渲染器

安装好 bat 之后，其他工具会自动调用它，不需要额外配置：

• fzf 文件预览：Ctrl+T 预览文件时，bat 负责渲染高亮
• yazi 代码预览：打开代码文件时，yazi 调用 bat 渲染
• git-delta：diff 输出的语法高亮底层也依赖 bat 的主题

bat 的主题配置会统一影响这些工具的显示效果，选主题时值得多试几个。

常见问题

bat 和 cat 有什么区别，能直接替换吗？

bat 是 cat 的超集，所有 cat 能做的 bat 都能做，额外增加语法高亮、行号、Git 标注和自动分页。用 alias cat="bat" 直接替换没有问题。如果某些脚本需要纯文本输出（不带颜色控制符），用 bat --plain 或单独保留 catp 别名。

eza 和 exa 什么关系？

eza 是从已停止维护的 exa fork 出来的社区维护版本，功能上基本兼容，额外修了一些 bug 并持续更新。如果你之前用 exa，换成 eza 直接改 alias 就行，命令参数基本相同。

glow 和 mdcat 图片显示的区别是什么？

glow 不支持内联图片，Markdown 里的图片会显示为纯文字链接。mdcat 在 kitty 终端下支持把图片直接渲染在终端里（Sixel 协议或 kitty 图形协议），文档里有配图的场景体验更完整。如果不用 kitty，两者在图片处理上没有差别。

这四个工具需要 Nerd Font 吗？

bat、glow、mdcat 不需要。eza 的 --icons 参数需要安装 Nerd Font，否则图标会显示为乱码。不想装字体的话，不加 --icons 参数正常使用即可。

终端模拟器：kitty

详细安装与配置见：Mac 终端基础配置：kitty + Zim

所有工具的运行基础。kitty 是一个用 GPU 渲染的高性能终端模拟器，启动快、滚动流畅，原生支持图片内联显示（这也是 yazi 文件预览图片能用的前提）。内置分屏（不依赖 tmux），支持标签页，配置文件是单个 kitty.conf，改起来比大多数终端直观。对于在终端里花大量时间的人，换一个渲染性能好的终端模拟器是性价比很高的基础投资。

Shell 框架：Zim

详细安装与配置见：Mac 终端基础配置：kitty + Zim

macOS 自带 zsh，但裸 zsh 体验很差。Zim 是一个轻量的 zsh 插件管理框架，比 Oh My Zsh 启动速度快很多，通过 .zimrc 声明需要的插件，装好后自动生效。

当前配置里启用的插件：

• fast-syntax-highlighting：实时高亮正在输入的命令，命令合法显绿色，输错显红色，按回车前就能发现拼写错误
• zsh-autosuggestions：根据历史记录实时预测补全建议，显示为灰色文字，按 → 接受，减少大量重复输入
• zsh-history-substring-search：按 ↑↓ 方向键时，按当前已输入内容做前缀匹配过滤历史，而不是顺序翻
• fzf-tab：把 Tab 补全的候选列表接管给 fzf，变成可交互过滤的模糊搜索界面
• steeef：Prompt 主题，展示用户名、当前路径、Git 分支和状态

Shell 增强工具

详细安装与配置见：终端搜索三件套：fzf + ripgrep + fd + jq

fzf

模糊搜索框架，单独使用时是一个交互式过滤器，真正的价值在于和其他命令组合。集成进 Zsh 后会接管三个快捷键：Ctrl+T 模糊搜索文件、Alt+C 模糊跳转目录、Ctrl+R 交互式搜索命令历史。配合上面的 fzf-tab，Tab 补全也变成模糊搜索界面。fzf 是整个工具链里”乘数效应”最强的一个——它本身不做什么，但让其他工具都变得更好用。

atuin

详细安装与配置见：Shell 历史与目录跳转的现代替代：atuin + zoxide

shell 历史记录的替代方案，把命令历史存进本地 SQLite 数据库，支持按时间、工作目录、退出码等维度检索。最直接的改变是 Ctrl+R 变成了带预览的全文搜索界面。还支持多设备历史同步，在不同 Mac 之间共享命令历史。

zoxide

cd 的智能替代品。记住访问过的目录，之后输入 z blog 就能直接跳到 /Users/you/code/github/blog-source，不需要输完整路径。项目目录多、路径深的开发者体验提升非常明显，是少数几个”装了就再也不想卸”的工具之一。

终端个性化

详细安装与配置见：终端启动界面：fastfetch + pokemon-colorscripts

fastfetch + pokemon-colorscripts

这两个组合使用：每次打开新终端，先随机展示一只宝可梦的彩色 ASCII 图，fastfetch 把系统信息（OS、CPU、内存、Shell、终端等）渲染在旁边。纯个性化，无实际功能，但比默认的空终端有意思很多。fastfetch 用 C 写成，启动速度远快于老牌的 neofetch，不会拖慢终端启动。

文件与搜索

ripgrep、fd、jq 的详细用法见：终端搜索三件套：fzf + ripgrep + fd + jq

ripgrep（rg）

比 grep 快一个数量级的全文搜索工具，默认递归搜索当前目录，自动忽略 .gitignore 里的文件。在大型代码仓库里搜索关键词，rg 的速度优势非常明显，输出带文件名、行号和彩色高亮。VSCode 的全局搜索底层用的也是 ripgrep。

fd

find 的现代替代品。默认大小写不敏感、忽略 .gitignore 内容、输出带颜色，语法比 find 直观很多——找 Go 文件直接 fd -e go，而不是 find . -name "*.go" -type f。和 fzf 结合使用效果更好。

bat

详细安装与配置见：文件查看升级：bat + eza + glow + mdcat

cat 的替代品，带语法高亮、行号，还有 Git 集成（在行号旁标注哪些行被修改过）。它也被很多其他工具用作底层渲染器——fzf 的文件预览、yazi 的代码预览默认都会调用 bat。

eza

ls 的现代替代品。默认输出带颜色，-l 模式下可以显示 Git 状态，--tree 模式展示目录树——这个功能直接取代了单独装 tree 命令的需求。配合 Nerd Font 字体还能显示文件类型图标，比原生 ls -la 的信息密度高很多。

yazi

详细安装与配置见：yazi：终端里的三栏文件管理器

终端里的文件管理器，基于 Rust 构建，速度很快。方向键导航目录、实时预览文件内容（代码、图片、PDF），批量操作文件。在 kitty 终端下能直接内联显示图片预览。对于不想离开终端但又需要浏览文件的场景，yazi 比反复 cd + ls 高效很多。.zshrc 里定义了 y 函数，退出 yazi 时会自动 cd 到最后所在目录。

jq

JSON 的命令行处理器，核心能力是对 JSON 进行查询、过滤、转换。调接口拿到 JSON 响应后，curl ... | jq '.data.items[] | .name' 这样的管道就能直接提取想要的字段。处理 API 响应、配置文件、日志分析时几乎不可缺少。

Git 工具

详细安装与配置见：终端里的 Git：git-delta + lazygit + gh

git-delta

Git diff 的语法高亮渲染器。配置进 ~/.gitconfig 后，git diff、git log -p、git show 的输出变成带语法高亮、行内差异标注的格式，比默认的加减号 diff 可读性高出不少。

lazygit

终端里的 Git TUI，用键盘操作就能完成暂存、提交、分支管理、rebase、stash 等常用 Git 操作，不用记忆大量命令参数。.zshrc 里设置了 alias lg=lazygit，快速调出。关于 lazygit 的常用工作流，后续会单独介绍。

gh

GitHub 官方 CLI。核心价值在于不离开终端就能操作 GitHub——创建 PR、查看 Issue、管理 Actions 工作流、查看 Review 评论。过去这些操作要切到浏览器，现在在命令行里完成，减少了大量上下文切换，在 CI/CD 调试、PR Review 来回改代码这类场景下体感尤其明显。

Markdown 渲染：glow / mdcat

详细安装与配置见：文件查看升级：bat + eza + glow + mdcat

glow

终端里的 Markdown 渲染器。glow README.md 直接把 Markdown 渲染成格式化输出——标题、加粗、代码块都有对应的视觉呈现。看项目文档、博客草稿时比 cat 体验好很多。

mdcat

同样是 Markdown 渲染工具，更轻量，在 kitty 终端下支持内联显示图片。文档里有图的场景，mdcat 的图文混排体验比 glow 更完整。

编辑器：Neovim + LazyVim

详细安装与配置见：从零开始用 Neovim：LazyVim 让配置不再是障碍

Neovim 是 Vim 的现代分支，支持 Lua 配置、LSP、Tree-sitter 语法高亮。但从零配置 Neovim 到可用状态需要花大量时间。

LazyVim 解决了这个问题——它是一套预配置的 Neovim 发行版，开箱即得代码补全、LSP、文件树、模糊搜索、Git 集成等功能。底层插件管理器是 lazy.nvim，按需懒加载插件，启动速度快。

配套工具 im-select 负责输入法自动切换：从 Neovim 的 Insert 模式退出时，自动把输入法切换回英文，避免进入 Normal 模式后还在中文状态下输入命令的问题。

LazyVim 的上手曲线比从零配置 Neovim 低很多，但整体还是需要适应 Vim 的模式操作。关于 LazyVim 的配置和常用插件，后续会单独介绍。

从哪里开始

按学习成本从低到高：

• 零成本，立竿见影：ripgrep、bat、eza、git-delta、zoxide、atuin——装上改个别名就能用
• 需要适应键位：fzf、lazygit、yazi——花半小时熟悉一下，之后回报持续
• 需要系统投入：LazyVim——上手慢，但配置完善后是全功能命令行 IDE

后续会针对 fzf、lazygit、LazyVim 单独写深入使用的文章。

做海外项目时，Google 一键登录几乎是标配。相比传统的邮箱注册流程（填邮箱→收验证码→设密码），用户只需要点一下 Google 按钮就能完成注册/登录，转化率能高不少。

本文以我自己的一个 Go 后端项目为例，分享 Google 一键登录的后端实现，技术栈是 GoFrame + JWT + MySQL。前端用的是 Google 官方的 Sign In With Google 按钮，后端只需要验证前端传过来的 ID Token 就行。

整体流程

Google 一键登录的核心流程其实很简单：

    participant U as 用户(浏览器)participant G as Googleparticipant B as 后端    U->>G: 1. 点击 Google 登录按钮，弹出授权窗口    G->>G: 2. 用户在 Google 页面完成身份验证    G->>U: 3. 返回 ID Token（JWT 格式）    U->>B: 4. POST /user/google-login {idToken}    B->>G: 5. 拉取 Google JWKS 公钥（有缓存）    G-->>B: 6. 返回公钥    B->>B: 7. 用公钥本地验证 ID Token 签名和有效期    B->>B: 8. 根据 googleID 查找/创建用户，签发 JWT    B->>U: 9. 返回 JWT + 用户信息  

后端要做的事只有三件：

1. 验证 ID Token——确认这个 token 确实是 Google 颁发的，且是给你的应用的
2. 查找或创建用户——第一次登录自动注册，后续登录直接查
3. 签发自己的 JWT——后续请求都走自己的鉴权体系

前置准备：Google Cloud Console 配置

环境依赖：

• Go 1.24
• GoFrame v2.10.0
• google.golang.org/api v0.259.0
• github.com/golang-jwt/jwt/v5 v5.3.0

在写代码之前，你需要去 Google Cloud Console 创建一个 OAuth 2.0 客户端：

1. 进入 APIs & Services → Credentials
2. 点 Create Credentials → OAuth client ID
3. 应用类型选 Web application
4. 配置 Authorized JavaScript origins（你的前端域名，比如 https://www.example.com）
5. 创建后拿到 Client ID 和 Client Secret

后端验证 ID Token 只需要 Client ID，不需要 Client Secret。

配置文件里加上：

1
2

google:
  clientId: "你的-client-id.apps.googleusercontent.com"

后端实现

1. 定义 API 接口

用 GoFrame 的结构化 API 定义：

1
2
3
4
5
6
7
8
9

type GoogleLoginReq struct {
    g.Meta  `path:"/user/google-login" method:"post" tags:"用户" summary:"Google一键登录"`
    IDToken string `json:"idToken" v:"required" dc:"Google ID Token"`
}

type GoogleLoginRes struct {
    Token string    `json:"token" dc:"JWT Token"`
    User  *UserInfo `json:"user" dc:"用户信息"`
}

前端只需要传一个 idToken 字段，就是 Google Sign In 回调里拿到的 credential。

2. 核心逻辑：验证 Token + 查建用户

这是整个 Google 登录的核心代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

package user

import (
    "context"

    v1 "your-project/api/user/v1"
    "your-project/internal/consts"
    "your-project/internal/dao"
    "your-project/internal/model/do"
    "your-project/internal/model/entity"
    "your-project/internal/service/jwt"
    "your-project/internal/utility/snowflake"

    "github.com/gogf/gf/v2/errors/gerror"
    "github.com/gogf/gf/v2/frame/g"
    "google.golang.org/api/idtoken"
)

func GoogleLogin(ctx context.Context, req *v1.GoogleLoginReq) (*v1.GoogleLoginRes, error) {
    // 1. 验证 Google ID Token
    clientID := g.Cfg().MustGet(ctx, "google.clientId").String()
    payload, err := idtoken.Validate(ctx, req.IDToken, clientID)
    if err != nil {
        g.Log().Error(ctx, "Google登录，Token验证失败", err)
        return nil, gerror.New("Google登录验证失败")
    }

    // 2. 从 payload 中提取用户信息
    googleID := payload.Subject
    email := payload.Claims["email"].(string)

    // 3. 查找已有用户
    var user *entity.Users
    err = dao.Users.Ctx(ctx).Where("google_id", googleID).Scan(&user)
    if err != nil {
        g.Log().Error(ctx, "Google登录，查询用户信息失败", err)
        return nil, gerror.New("系统错误")
    }

    // 4. 用户不存在则自动注册
    if user == nil {
        uid := snowflake.GenerateID()
        _, err = dao.Users.Ctx(ctx).Insert(do.Users{
            Uid:              uid,
            Email:            email,
            GoogleId:         googleID,
            RegisterType:     consts.RegisterTypeGoogle,
            MembershipStatus: consts.MembershipStatusNonMember,
            Status:           consts.UserStatusNormal,
        })
        if err != nil {
            g.Log().Error(ctx, "Google登录，创建用户失败", err)
            return nil, gerror.New("系统错误")
        }

        err = dao.Users.Ctx(ctx).Where("uid", uid).Scan(&user)
        if err != nil {
            return nil, gerror.New("系统错误")
        }
    }

    // 5. 检查账号状态
    if user.Status != consts.UserStatusNormal {
        return nil, gerror.New("账号已被禁用")
    }

    // 6. 签发自己的 JWT
    token, err := jwt.GenerateToken(user.Uid, user.Email)
    if err != nil {
        return nil, gerror.New("系统错误")
    }

    return &v1.GoogleLoginRes{
        Token: token,
        User: &v1.UserInfo{
            UID:   user.Uid,
            Email: user.Email,
            // ... 其他字段
        },
    }, nil
}

逐步拆解：

验证 ID Token

1

payload, err := idtoken.Validate(ctx, req.IDToken, clientID)

google.golang.org/api/idtoken 包帮你做了所有脏活：

• 从 Google 的 JWKS 端点拉取公钥
• 验证 token 签名
• 检查 aud（audience）是否匹配你的 Client ID
• 检查 token 是否过期

验证通过后，payload.Subject 就是用户的 Google ID（全局唯一且不变），payload.Claims 里有 email、name、picture 等信息。

查找或创建用户

用 google_id 作为关联字段查用户表。如果查不到说明是新用户，自动创建一条记录。这里用了 Snowflake 算法生成分布式唯一 ID 作为业务主键。

为什么用 google_id 而不是 email 来关联？ 因为用户可能会改 Google 账号的邮箱，但 Subject（Google ID）是永远不变的。

签发 JWT

验证完 Google 身份后，后续的鉴权还是走自己的 JWT 体系。这样做的好处是：

• 不依赖 Google 的 token 有效期
• 可以统一处理邮箱注册和 Google 注册的用户
• 中间件只需要解析自己的 JWT，不用区分登录方式

3. JWT 签发与验证

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

func GenerateToken(uid, email string) (string, error) {
    ctx := context.Background()
    secret := g.Cfg().MustGet(ctx, "jwt.secret").String()
    expire := g.Cfg().MustGet(ctx, "jwt.expire", 7200).Int()

    claims := Claims{
        UID:   uid,
        Email: email,
        RegisteredClaims: jwt.RegisteredClaims{
            ID:        uuid.NewString(),
            ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Duration(expire) * time.Second)),
            IssuedAt:  jwt.NewNumericDate(time.Now()),
        },
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString([]byte(secret))
}

每个 JWT 都有一个 UUID 作为 jti（JWT ID），配合 Redis 黑名单可以实现主动吊销 token（比如用户退出登录时）。

4. 路由注册

Google 登录接口放在无需鉴权的公开路由组里：

1

group.POST("/user/google-login", user.NewV1().GoogleLogin)

跟普通的邮箱登录接口并列，登录成功后返回的数据格式完全一致——前端拿到 token 存起来，后续请求带上就行。

数据库设计要点

users 表需要加几个字段：

1
2
3

ALTER TABLE users ADD COLUMN google_id VARCHAR(128) DEFAULT NULL COMMENT 'Google用户ID';
ALTER TABLE users ADD COLUMN register_type TINYINT UNSIGNED DEFAULT 1 COMMENT '注册类型：1-邮箱 2-Google';
ALTER TABLE users ADD UNIQUE INDEX idx_google_id (google_id);

• google_id 加唯一索引，防止重复绑定
• register_type 区分注册来源，后续做数据分析有用
• email 字段对 Google 用户也保留，方便发通知邮件

安全注意事项

1. 永远在后端验证 ID Token——前端传过来的 token 不可信，必须后端调 Google API 验证
2. 校验 audience——idtoken.Validate 的第三个参数就是你的 Client ID，防止其他应用的 token 被拿来登录你的系统
3. 不要把 Client Secret 暴露到前端——ID Token 验证方案不需要 Client Secret，但如果你用 Authorization Code 方案就需要，记得只放后端
4. google_id 用唯一索引——防止并发场景下创建重复用户

前端怎么接？

前端用的是 Google Identity Services（GIS），这是 Google 2021 年推出的新版登录 SDK，取代了老版的 google-signin 库。整个接入只需三步。

第一步：引入 GIS 脚本

在 HTML 的 <head> 里加上：

1

<script src="https://accounts.google.com/gsi/client" async defer></script>

async defer 让脚本异步加载，不阻塞页面渲染。

第二步：放置登录按钮

有两种方式，按需选一种：

方式一：纯 HTML（最简单）

直接在页面放两个 div，GIS 脚本加载后会自动处理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<!-- 配置项：Client ID 和回调函数名 -->
<div id="g_id_onload"
     data-client_id="你的-client-id.apps.googleusercontent.com"
     data-callback="handleCredentialResponse">
</div>

<!-- 渲染 Google 样式的登录按钮 -->
<div class="g_id_signin"
     data-type="standard"
     data-size="large"
     data-theme="outline"
     data-text="sign_in_with"
     data-shape="rectangular">
</div>

• data-client_id：换成你在 Google Cloud Console 拿到的 Client ID
• data-callback：登录成功后调用的 JavaScript 函数名
• g_id_signin 的 data-theme、data-size 等属性控制按钮外观，Google 官方文档有完整参数列表

方式二：JavaScript API（更灵活）

需要在特定时机触发登录、或者想启用 One Tap 弹窗时，用 JS 控制更方便：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

window.onload = function () {
  google.accounts.id.initialize({
    client_id: "你的-client-id.apps.googleusercontent.com",
    callback: handleCredentialResponse,
  });

  // 把按钮渲染到指定容器
  google.accounts.id.renderButton(
    document.getElementById("googleSignInBtn"),
    { theme: "outline", size: "large" }
  );

  // 同时弹出 One Tap 提示（可选）
  // google.accounts.id.prompt();
};

1

<div id="googleSignInBtn"></div>

第三步：处理回调、调后端接口

登录成功后，Google 会调用你配置的回调函数，参数里的 credential 字段就是 ID Token——一段很长的 JWT 字符串，直接传给后端就行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21