Unity 鼠标光标设置避坑指南：Cursor.SetCursor 与 Texture2D 导入配置的 5 个关键细节

1. Unity 光标自定义踩坑现场：为什么你的鼠标总是偏一截

Unity 里换鼠标光标这件事，看起来就是一行Cursor.SetCursor的事，但真正上手你会发现坑一个接一个：图片导进去变模糊、热点对不上、编辑器里好好的打包后光标没了、Windows 上正常 macOS 上偏移、CursorMode.Auto和ForceSoftware到底选哪个。这些问题我在做绘图工具和编辑器扩展时几乎全踩过一遍，所以这篇把Cursor.SetCursor和Texture2D导入配置的关键细节拆开讲，给你能直接复制的代码和导入参数。

先把核心 API 摆出来，Cursor.SetCursor的签名是三个参数：

public static void SetCursor(Texture2D texture, Vector2 hotspot, CursorMode cursorMode);

第一个参数是光标贴图，第二个是热点坐标（hotspot），第三个是渲染模式。三个参数每一个都有坑，而且坑和坑之间会互相放大。比如你热点算错了，又用了CursorMode.Auto，在硬件光标被系统缩放的情况下，偏移量会被再放大一次，表现出来就是"笔尖在左上、线条画在右下"这种诡异现象。

这篇适合谁：正在用 Unity 做绘图、编辑器工具、自定义交互 UI，需要把系统默认箭头换成画笔、十字准星、抓手等自定义光标的开发者。下面按"问题场景 → 前置准备 → 可复制配置 → 验证 → 排错 → 延伸"的顺序走，每一步都给具体参数和代码，你可以边看边在工程里对照改。

先明确一个概念：热点（hotspot）是光标贴图上"真正代表点击位置"的那个像素点。系统默认箭头热点在左上角 (0,0)，十字准星热点在正中心。你换成画笔图片，热点就应该落在笔尖上，否则用户看到的笔尖和实际点击位置差一截，画线自然就歪。这个坐标系是以贴图左下角为原点、向右为 X、向上为 Y，和 Unity 屏幕坐标一致，但和很多图片编辑软件（左上角为原点）相反，这是第一个高频错误来源。

2. 前置准备：TaoToken 接入与工程环境确认

在写光标代码之前，先把两件事定下来：一是工程里贴图的导入管线，二是如果你打算用 AI 辅助生成光标资源或排查脚本逻辑，把模型调用通道准备好。后者我用 TaoToken 来做，它的 API 地址是https://taotoken.net/api，兼容 OpenAI 风格的接口，拿来跑代码解释、生成 Texture2D 导入脚本、分析报错信息都顺手。

先说工程侧的前置确认。打开你的 Unity 工程，确认三件事：

第一，光标贴图放在哪个目录。推荐放在Assets/Resources/Cursors/下，因为Resources.Load是最省事的加载方式，路径不带扩展名。如果你用 Addressables 或 AssetBundle，加载逻辑要相应改，但导入设置是一样的。

第二，确认 Unity 版本。Cursor.SetCursor在 2019 之后的版本行为基本一致，但CursorMode在部分平台的支持情况有差异，后面第 5 节会细讲。你可以在Help > About Unity里看到版本号，记下来，排错时有用。

第三，确认目标平台。Windows、macOS、Linux、WebGL 对硬件光标和软件光标的支持不一样，这直接决定你CursorMode怎么选。如果你只做 Windows 单平台，选择空间大；如果要多平台，就得按最保守的方案来。

再说 TaoToken 侧的准备。你需要一个 API Key，在控制台创建即可，地址是https://taotoken.net/api-keys。创建后拿到形如sk-xxxx的密钥，别硬编码进脚本，用环境变量或者本地配置文件管理。下面这段是验证通道可用的最小请求，你可以先用它确认 Key 和网络都通：

curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -d '{ "model": "gpt-4o-mini", "messages": [ {"role": "user", "content": "用一句话解释 Unity Cursor.SetCursor 的 hotspot 参数含义"} ] }'

返回里能看到choices[0].message.content就说明通道正常。这一步不是必须的，但如果你后面想让模型帮你生成一批不同尺寸的光标导入配置，或者把报错日志丢进去分析，先把通道打通会省很多来回。模型对话入口在https://taotoken.net/models，你可以在网页里直接试，不用先写代码。

工程和通道都就绪后，进入下一节，开始配贴图导入参数和光标脚本。这里提醒一句：光标贴图的导入设置比代码更容易出错，因为 Unity 默认的导入参数是为普通 2D 精灵优化的，不是为光标优化的，直接拖进去十有八九会模糊或尺寸不对。

3. 可复制配置：Texture2D 导入参数与 Cursor.SetCursor 脚本

这一节是全文的核心，给你两份可直接用的配置：一份是贴图导入参数（对应.meta文件里的关键字段），一份是光标管理脚本。先讲导入，再讲代码，最后给一个 JSON 形式的配置清单方便你对照。

3.1 Texture2D 导入设置：五个必须改的字段

把光标 PNG 拖进Assets/Resources/Cursors/后，选中它，在 Inspector 里按下面改。这些字段最终会写进.meta文件，团队协作时可以直接提交.meta保证一致。

最容易忽略的是Filter Mode和Compression。默认是 Bilinear + 压缩，一张 64x64 的画笔光标导进去，笔尖边缘会糊成一团，用户看着像"光标没对准"。改成 Point + None 之后立刻锐利。另外Max Size默认 2048 一般够用，但如果你导入的是 128x128 光标而 Max Size 被手动调成 32，Unity 会缩采样，热点坐标就全乱了。

如果你要批量处理，可以在AssetPostprocessor里统一设置，避免每张图手改：

using UnityEditor; using UnityEngine; public class CursorTextureImporter : AssetPostprocessor { void OnPreprocessTexture() { if (!assetPath.Contains("/Resources/Cursors/")) return; TextureImporter importer = (TextureImporter)assetImporter; importer.textureType = TextureImporterType.Cursor; importer.alphaIsTransparency = true; importer.isReadable = false; importer.mipmapEnabled = false; importer.wrapMode = TextureWrapMode.Clamp; importer.filterMode = FilterMode.Point; importer.textureCompression = TextureImporterCompression.Uncompressed; importer.maxTextureSize = 256; } }

这段放在Assets/Editor/下，之后所有放进Resources/Cursors/的图都会自动套用这套参数，团队里也不会有人漏改。

3.2 光标管理脚本：热点计算与模式选择

下面是完整的光标管理脚本，包含加载、热点计算、模式切换和恢复默认。热点用贴图尺寸的比例来算，避免硬编码像素值导致换图就错位。

using UnityEngine; public class CursorController : MonoBehaviour { [Header("光标贴图（放在 Resources/Cursors/ 下）")] public string cursorResourcePath = "Cursors/brush"; [Header("热点：以贴图左下角为原点，单位像素")] public Vector2 hotspot = new Vector2(0f, 0f); [Header("渲染模式")] public CursorMode cursorMode = CursorMode.Auto; private Texture2D _cursorTex; void Start() { _cursorTex = Resources.Load<Texture2D>(cursorResourcePath); if (_cursorTex == null) { Debug.LogError($"光标贴图加载失败: {cursorResourcePath}"); return; } ApplyCursor(); } public void ApplyCursor() { if (_cursorTex == null) return; Cursor.SetCursor(_cursorTex, hotspot, cursorMode); } public void ResetToDefault() { Cursor.SetCursor(null, Vector2.zero, CursorMode.Auto); } void OnDisable() { ResetToDefault(); } }

热点怎么填？假设你的画笔贴图是 32x32，笔尖在左下角，那热点就是(0, 0)；笔尖在正中心，热点是(16, 16)；笔尖在右下角，热点是(32, 0)。注意 Y 轴向上，所以"左下角"是(0,0)，"左上角"是(0,32)。这和很多图片软件里"左上角为原点"的直觉相反，是偏移问题的头号原因。

如果你想让热点跟着贴图尺寸自动算，可以加一个按比例的工具方法：

public static Vector2 HotspotByRatio(Texture2D tex, float xRatio, float yRatio) { return new Vector2(tex.width * xRatio, tex.height * yRatio); }

比如笔尖在贴图左下角，传(0f, 0f)；在正中心传(0.5f, 0.5f)。这样换尺寸不同的贴图也不用改代码。

3.3 配置清单（JSON 形式，便于对照）

把上面的关键参数整理成一份清单，你可以直接贴进团队文档：

{ "cursorTexture": { "path": "Assets/Resources/Cursors/brush.png", "textureType": "Cursor", "alphaIsTransparency": true, "isReadable": false, "mipmapEnabled": false, "wrapMode": "Clamp", "filterMode": "Point", "compression": "None", "maxTextureSize": 256 }, "cursorSetCursor": { "texture": "Resources/Cursors/brush", "hotspot": [0, 0], "cursorMode": "Auto" } }

hotspot这里写的是像素坐标，实际项目里建议用 3.2 节的比例方法算，避免换图重填。cursorMode的选择逻辑见第 5 节排错部分，先按Auto起步，遇到平台问题再切。

4. 验证请求与成功结果：运行时确认光标真的生效

配置写完，怎么确认光标真的按预期工作？分三步验证：编辑器内验证、运行时日志验证、打包后验证。每一步都给具体操作和预期结果。

4.1 编辑器内快速验证

把CursorController挂到场景里任意 GameObject 上，cursorResourcePath填Cursors/brush，hotspot填(0,0)，运行。预期结果：鼠标移到 Game 视图里，光标变成你的画笔图，笔尖对准实际点击位置。如果光标没变，先看 Console 有没有"光标贴图加载失败"的报错，有的话检查路径和贴图是否在Resources下。

这里有个编辑器特有的坑：Game 视图里光标可能不刷新，尤其是你改了贴图导入设置之后。解决办法是点一下 Game 视图再移出去，或者重启编辑器。这不是代码问题，是编辑器缓存。

4.2 运行时日志验证

在ApplyCursor里加一行日志，确认贴图尺寸和热点值符合预期：

Debug.Log($"光标尺寸: {_cursorTex.width}x{_cursorTex.height}, 热点: {hotspot}, 模式: {cursorMode}");

预期输出类似光标尺寸: 32x32, 热点: (0.0, 0.0), 模式: Auto。如果尺寸和你导入的原图不一致，说明 Max Size 或压缩设置把它改了，回第 3.1 节检查。如果热点值和你填的不一样，检查是不是在 Inspector 里被别的脚本覆盖了。

4.3 打包后验证与平台差异

编辑器里正常不代表打包后正常。打一个 Windows 包，运行 exe，重点看两件事：光标是否显示、热点是否对齐。Windows 上CursorMode.Auto通常走硬件光标，表现和编辑器一致；如果发现光标尺寸被系统缩放（比如 125% DPI 下变大），说明硬件光标被系统接管了，这时切ForceSoftware可以强制用软件渲染，尺寸由你控制，但会有轻微延迟。

macOS 上要注意 Retina 屏，硬件光标可能被系统按 2x 缩放，热点坐标要按逻辑像素算而不是物理像素。WebGL 平台对自定义光标支持有限，部分浏览器会忽略SetCursor，建议在 WebGL 下做降级处理，用 UI 元素模拟光标。

验证通过的标准：在目标平台上，光标显示清晰、热点对准点击位置、切换场景后光标不丢失。三条都满足，这一节就算过了。

5. 本篇常见错排查：401、光标模糊、热点偏移与平台差异

这一节按真实报错和现象来排，每条给现象、原因、解决。先列一个速查表，再逐条展开。

逐条说。光标模糊是最常见的，九成是 Filter Mode 没改。Unity 默认 Bilinear，光标这种小图放大显示时插值会糊。改成 Point 立刻锐利。如果还糊，检查 Compression 是不是被设成了 Normal Quality，改成 None。

热点偏移排第二。典型现象是"我明明把热点设成笔尖了，画出来的线还是偏"。原因几乎都是坐标系搞反：你以为 (0,0) 是左上角，实际 Unity 是左下角。一张 32x32 图，笔尖在左上角，正确热点是(0, 32)而不是(0, 0)。用 3.2 节的比例方法可以规避。

光标尺寸不对，先看 Max Size。如果你导入 128x128 光标但 Max Size 是 64，Unity 会缩到 64，热点按 128 算就全错。把 Max Size 调到不小于原图尺寸。如果尺寸对但显示被系统放大，是 DPI 缩放，切CursorMode.ForceSoftware试试。

打包后光标消失，检查贴图是否真的在Resources目录下（大小写敏感，resources不行），以及Resources.Load的路径是否带扩展名（不能带）。另外确认贴图没被剔除，Build 时看Resources是否包含。

401 报错出现在你调模型接口时，说明 Key 没带对。检查Authorization: Bearer sk-xxx头是否完整，Key 是否过期。没有 choices 字段通常是请求体 JSON 格式错，比如messages写成了字符串而不是数组。local proxy failed是网络层问题，检查系统代理设置，直连重试。OAuth 报错说明你用了网页登录的认证方式调 API，改成 API Key 方式即可。

排错时如果拿不准，可以把报错日志丢给模型分析，通道用第 2 节配好的那个。但注意别把 Key 贴进对话里。

6. 延伸：把光标配置沉淀成团队规范

光标这件事单次做对不难，难的是团队里每个人都做对。我的做法是把第 3 节的导入脚本和光标管理脚本放进公共包，新项目直接引用，.meta文件随贴图一起提交，Code Review 时重点看三个字段：Filter Mode、Compression、Max Size。这三个对了，八成问题就没了。

另外建议给光标资源定个命名规范，比如cursor_brush_32.png、cursor_crosshair_64.png，尺寸写进文件名，热点在脚本里按比例算，换图不用改代码。多平台项目在 CI 里加一步打包后截图对比，确认光标显示正常再发版。

如果你想让模型帮你批量生成不同尺寸的光标导入配置，或者把一段光标相关报错整理成排查清单，可以用https://taotoken.net/api这个通道，Key 在https://taotoken.net/api-keys创建，接入文档在https://taotoken.net/doc。长期做编辑器工具或 Agent 类项目的，Coding Plan 在https://taotoken.net/coding-plan，按需选就行。

最后留一个实操建议：下次改光标，先把贴图导入参数按 3.1 节的表过一遍，再跑 3.2 节的脚本，最后按第 4 节三步验证。顺序别乱，乱了就容易在"到底是贴图问题还是代码问题"之间来回猜。