1. 从窗口里“消失”的鼠标：ShowCursor 与 ClipCursor 到底能做什么

做 Windows 桌面应用时，鼠标光标有时候是个麻烦。全屏播放器里它不该出现，游戏窗口里它不该乱跑，演示工具里它最好乖乖待在指定区域。你搜“Windows 鼠标隐藏”，大概率会先看到ShowCursor，但真正上手就会发现：调了ShowCursor(FALSE)，鼠标出了窗口又冒出来了；想锁住位置，又不知道ClipCursor的矩形该怎么算。

这篇就围绕三个 API 讲清楚：ShowCursor负责光标的显示计数，ClipCursor负责把光标限制在屏幕某个矩形内，CreateWindowEx负责创建一个不抢焦点、不上任务栏的辅助窗口来配合前两者。适合正在写全屏播放器、游戏客户端、远程控制或演示类工具的开发者，也适合刚接触 Win32 消息循环、想找一个能跑起来的小案例练手的人。

核心检索词先摆出来：Windows 鼠标隐藏、ShowCursor 用法、ClipCursor 限制鼠标区域、CreateWindowEx 创建透明窗口。这几个词会贯穿全文，每一步都有可复制的代码和验证方法。

需要先建立一个认知：ShowCursor不是“设置鼠标可见性”的开关，而是一个计数器。系统内部维护一个显示计数，初始值通常是 0（显示状态）。你调一次ShowCursor(FALSE)，计数减一，变成 -1，光标隐藏；再调一次，变成 -2，还是隐藏。想恢复显示，必须调ShowCursor(TRUE)把计数加回来，加到 0 或以上才重新显示。这就是为什么很多人隐藏了鼠标却怎么都显示不回来——隐藏了几次就得显示几次。

ClipCursor则是另一套逻辑，它接收一个RECT指针，把光标物理限制在这个矩形内。传NULL就解除限制。它和ShowCursor互不干扰：一个管“看不看得见”，一个管“跑不跑得出去”。全屏场景里两者经常一起用，先隐藏再锁定，体验才完整。

还有一个容易被忽略的点：ShowCursor的调用线程必须和创建窗口的线程是同一个。如果你在子线程里调，很可能不生效。这是 Win32 窗口消息机制决定的，光标状态跟窗口线程绑定。所以正确做法是在窗口过程（WndProc）里、或者与创建窗口同一线程的代码路径中调用。

下面从零搭一个最小可运行工程，把这三个 API 串起来。工程用纯 Win32，不依赖 MFC 或 Qt，编译环境用 Visual Studio 的 cl.exe 或 MinGW 都行。我会给出完整代码、编译命令、验证步骤，以及几个真实会踩的坑。

2. 前置准备：用 TaoToken 统一管理 AI 辅助开发工具的接入

写 Win32 代码时，我习惯让 AI 帮忙补全消息处理、检查RECT计算、解释GetSystemMetrics的返回值。但工具一多，Key 和 Base URL 就散落在各个配置文件里：Cline 一个、Codex 一个、Claude Code 一个，改起来容易漏。TaoToken 的作用就是把这些 AI 辅助开发工具的接入通道统一起来，一个 Key、一个 API 地址，减少来回切换配置的成本。

它的接入信息很直接：

• 官网地址：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API 地址：https://taotoken.net/api
• 模型对话入口：https://taotoken.net/api/chat
• Coding Plan（长期编码/Agent 场景）：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• 控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• Claude Code Anthropic 接入：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

如果你用的是 Cline 或 Claude Code 这类工具，配置通常落在settings.json或auth.json里。以 Cline 的 MCP 配置为例，一个可复制的片段长这样：

{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@taotoken/mcp-server"], "env": { "TAOTOKEN_API_KEY": "sk-你的Key", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } } } }

Codex 的auth.json则是另一种结构，核心三件套是 Base URL、Key、Model ID：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "model": "claude-sonnet-4-20250514" }

Claude Code 走 Anthropic 兼容通道时，环境变量方式更省事：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key"

这里要强调：Base URL、Key、Model ID 三件套缺一不可。只填 Key 不填 Base URL，请求会打到默认地址；只填 Base URL 不填 Model ID，部分工具会报模型不存在。配置完先跑一次模型对话验证通道是否通，再去写 Win32 代码，避免把网络问题和代码问题混在一起排查。

TaoToken 在这里的角色是“统一入口”，不是替代你的编辑器或编译器。Win32 代码还是在本地的 Visual Studio 或 VS Code 里写，AI 只是辅助补全和解释。把 Key 管好，后面调试ShowCursor计数、ClipCursor矩形时，遇到不懂的 API 行为可以直接问，效率会高不少。

3. 可复制配置：CreateWindowEx + ShowCursor + ClipCursor 完整代码

这一节给出一份能直接编译运行的 Win32 工程。目标：创建一个全屏无边框窗口，进入后隐藏鼠标并把光标锁在窗口内，按 Esc 退出时恢复鼠标和解除锁定。

先看窗口创建。用CreateWindowEx而不是CreateWindow，因为我们需要扩展样式：WS_EX_TOPMOST让窗口置顶，WS_EX_TOOLWINDOW让它不出现在任务栏和 Alt+Tab 列表里，WS_EX_TRANSPARENT在需要穿透点击时用（本例全屏窗口不需要穿透，先不加）。

#include <windows.h> #define IDT_CHECK 1 HWND g_hwnd = NULL; RECT g_oldClip; BOOL g_cursorHidden = FALSE; LRESULT CALLBACK WndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) { switch (msg) { case WM_CREATE: // 保存原始裁剪区域，退出时恢复 GetClipCursor(&g_oldClip); // 隐藏光标：计数减一 ShowCursor(FALSE); g_cursorHidden = TRUE; // 把光标锁在窗口客户区 { RECT rc; GetClientRect(hwnd, &rc); POINT pt = {0, 0}; ClientToScreen(hwnd, &pt); rc.left += pt.x; rc.top += pt.y; rc.right += pt.x; rc.bottom += pt.y; ClipCursor(&rc); } SetTimer(hwnd, IDT_CHECK, 100, NULL); return 0; case WM_TIMER: // 定时重新锁定，防止其他程序抢走裁剪区域 if (wParam == IDT_CHECK) { RECT rc; GetClientRect(hwnd, &rc); POINT pt = {0, 0}; ClientToScreen(hwnd, &pt); rc.left += pt.x; rc.top += pt.y; rc.right += pt.x; rc.bottom += pt.y; ClipCursor(&rc); } return 0; case WM_KEYDOWN: if (wParam == VK_ESCAPE) { DestroyWindow(hwnd); } return 0; case WM_DESTROY: KillTimer(hwnd, IDT_CHECK); ClipCursor(&g_oldClip); // 恢复原始裁剪区域 if (g_cursorHidden) { ShowCursor(TRUE); // 计数加一，恢复显示 g_cursorHidden = FALSE; } PostQuitMessage(0); return 0; } return DefWindowProc(hwnd, msg, wParam, lParam); } int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR lpCmd, int nShow) { WNDCLASSEX wc = {0}; wc.cbSize = sizeof(WNDCLASSEX); wc.lpfnWndProc = WndProc; wc.hInstance = hInst; wc.lpszClassName = L"FullScreenMouseHide"; wc.hCursor = NULL; // 不设置默认光标 RegisterClassEx(&wc); int sw = GetSystemMetrics(SM_CXSCREEN); int sh = GetSystemMetrics(SM_CYSCREEN); g_hwnd = CreateWindowEx( WS_EX_TOPMOST | WS_EX_TOOLWINDOW, L"FullScreenMouseHide", L"Mouse Hide Demo", WS_POPUP | WS_VISIBLE, 0, 0, sw, sh, NULL, NULL, hInst, NULL); if (!g_hwnd) return 1; ShowWindow(g_hwnd, nShow); UpdateWindow(g_hwnd); MSG msg; while (GetMessage(&msg, NULL, 0, 0)) { TranslateMessage(&msg); DispatchMessage(&msg); } return (int)msg.wParam; }

编译命令（MinGW 环境）：

gcc mouse_hide.c -o mouse_hide.exe -mwindows -lgdi32 -luser32

Visual Studio 开发者命令提示符下：

cl mouse_hide.c /link user32.lib gdi32.lib /SUBSYSTEM:WINDOWS

几个关键参数说明，用表格对照更清楚：

注意ClientToScreen的用法：GetClientRect拿到的是客户区坐标（左上角为 0,0），必须转成屏幕坐标才能传给ClipCursor。很多人直接传GetClientRect的结果，结果光标被锁在屏幕左上角一小块区域，就是这个原因。

WM_TIMER里每 100ms 重新ClipCursor一次，是因为其他程序（比如某些游戏、远程桌面）可能修改全局裁剪区域。定时重设是一种简单可靠的兜底。如果你追求更精细，可以监听WM_ACTIVATE，在窗口激活时重设。

ShowCursor的计数问题在这里体现得很清楚：进入时减一，退出时加一，配对出现。如果你在代码里多处调用ShowCursor(FALSE)，就必须保证有同样次数的ShowCursor(TRUE)。建议用一个布尔变量记录状态，避免重复隐藏。

4. 验证请求与成功结果：怎么确认鼠标真的被隐藏和锁定了

代码跑起来后，怎么确认行为符合预期？分三步验证。

第一步，观察光标可见性。运行mouse_hide.exe，窗口全屏铺满，鼠标光标应该立刻消失。移动鼠标，光标不出现。此时按 Esc，窗口关闭，光标恢复。如果光标没消失，先检查ShowCursor(FALSE)是否在WM_CREATE里被调用，以及是否和创建窗口在同一线程。

第二步，验证ClipCursor是否生效。把窗口改成非全屏，比如 800x600，放在屏幕中间。运行后移动鼠标，光标应该被限制在这个 800x600 矩形内，无法移到窗口外面。你可以用GetCursorPos打印坐标来确认：

POINT pt; GetCursorPos(&pt); char buf[64]; wsprintfA(buf, "Cursor: %d, %d\n", pt.x, pt.y); OutputDebugStringA(buf);

在调试器里观察输出，坐标不会超出窗口矩形范围。如果坐标能跑到窗口外，说明ClipCursor的矩形算错了，重点检查ClientToScreen有没有调用。

第三步，验证退出恢复。按 Esc 关闭窗口后，光标应该重新出现，并且可以自由移动到屏幕任何位置。如果光标还是不显示，说明ShowCursor(TRUE)没执行，或者隐藏次数多于显示次数。可以在WM_DESTROY里加日志确认。

一个更直观的验证方法：开两个显示器或分屏，把窗口放一边，鼠标往另一边移。如果ClipCursor生效，鼠标会被“挡”在窗口边界。这个体感测试比看坐标更直接。

成功结果应该是：进入窗口光标消失且无法移出，退出后一切恢复正常。如果中间有任何一步不对，下一节列出常见报错和排查路径。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 对照

调试 Win32 代码时，报错往往不在 API 本身，而在环境或配置。下面几个是真实会遇到的，逐个对照。

401 Unauthorized：如果你在用 AI 工具辅助写代码，请求模型时返回 401，通常是 Key 无效或没带上。检查TAOTOKEN_API_KEY是否填对，Base URL 是否是https://taotoken.net/api。注意 Key 不要有多余空格，环境变量导出后可以用echo $TAOTOKEN_API_KEY确认。

local proxy failed：这个报错一般出现在工具尝试走本地代理但代理没启动时。检查你的工具配置里是否误设了http_proxy或https_proxy环境变量。如果有，先unset掉再试。TaoToken 的接入不需要本地代理，直接填 API 地址即可。

reading choices 相关报错：这类错误通常出现在解析模型返回时，返回体里没有choices字段。原因可能是 Model ID 填错，或者请求打到了不兼容的端点。确认三件套：Base URL、Key、Model ID。Model ID 要和你实际使用的模型一致，比如claude-sonnet-4-20250514，不要写成显示名称。

OAuth 相关报错：Claude Code 走 Anthropic 通道时，如果同时配了 OAuth 和 API Key，可能冲突。建议只保留一种认证方式。用 API Key 时，确保ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL都设置正确，不要留空的 OAuth token 文件。

回到 Win32 本身，还有两个高频坑：

一是ShowCursor不生效。最常见原因是调用线程不对。ShowCursor影响的是调用线程关联的窗口站，必须在创建窗口的同一线程调用。如果你在WinMain里创建窗口，就在WinMain或WndProc里调，别丢到std::thread里。

二是ClipCursor锁不住。检查RECT是否用了屏幕坐标。GetClientRect返回客户区坐标，必须ClientToScreen转换。另外，如果窗口有边框，客户区比窗口小，锁定的区域会略小于窗口，这是正常的。

排查顺序建议：先确认代码编译通过、窗口能正常显示，再验证ShowCursor，最后验证ClipCursor。不要三个一起调，容易互相干扰。

6. 继续深入：把光标控制接入你的 AI 辅助开发流程

光标隐藏和区域锁定只是 Win32 窗口交互的一小部分。实际项目里，你可能还需要处理多显示器下的ClipCursor矩形计算、窗口失去焦点时的光标恢复、以及全屏切换时的状态同步。这些场景下，让 AI 辅助工具帮你检查RECT计算、解释GetSystemMetrics在不同 DPI 下的返回值，能省不少时间。

如果你长期做 Windows 桌面开发，建议把 AI 辅助工具的接入统一到 TaoToken 的 Coding Plan，一个 Key 覆盖日常编码和 Agent 场景，配置一次到处能用。需要验证模型是否正常时，走模型对话入口发一条测试消息即可。API Keys 在控制台管理，接入细节看文档。

最后留一个实用技巧：调试ShowCursor计数时，可以在关键路径加OutputDebugString打印当前调用次数，配合 DebugView 观察。比反复猜“到底隐藏了几次”高效得多。代码跑通后，把WM_TIMER的 100ms 改成 500ms 或去掉，观察ClipCursor是否还会被其他程序抢走，根据实际环境决定要不要保留定时重设。