★ FEATURED ARTICLE 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保证一致。字段推荐值原因Texture TypeCursor专用类型Unity 会按光标规则处理Texture Shape2D光标不支持立方体贴图Alpha Is Transparency勾选保证透明边缘不发黑Read/Write关闭光标不需要 CPU 读回省内存Generate Mip Maps关闭光标是 1:1 显示Mipmap 会导致模糊Wrap ModeClamp防止边缘采样溢出Filter ModePoint (no filter)像素风光标必须点采样否则糊Max Size不小于贴图实际尺寸被压到 32 会导致大光标失真CompressionNone压缩会产生色块和透明边缘噪点最容易忽略的是Filter Mode和Compression。默认是 Bilinear 压缩一张 64x64 的画笔光标导进去笔尖边缘会糊成一团用户看着像光标没对准。改成 Point None 之后立刻锐利。另外Max Size默认 2048 一般够用但如果你导入的是 128x128 光标而 Max Size 被手动调成 32Unity 会缩采样热点坐标就全乱了。如果你要批量处理可以在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.LoadTexture2D(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/brushhotspot填(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 是 Bilinear 或贴图被压缩改 Point None热点偏移点击位置和光标差一截热点坐标系搞反左上 vs 左下按左下角原点重算光标尺寸不对、被放大缩小Max Size 限制或 DPI 缩放调 Max Size必要时 ForceSoftware打包后光标消失贴图没进包或路径大小写不一致检查 Resources 路径调用模型接口返回 401API Key 无效或没带 Authorization 头检查 Key 和环境变量返回里没有 choices 字段请求体格式错或模型名不对对照官方请求示例本地代理报错 local proxy failed网络层拦截或代理配置冲突检查系统代理设置直连重试OAuth 相关报错认证方式不匹配改用 API Key 方式调用逐条说。光标模糊是最常见的九成是 Filter Mode 没改。Unity 默认 Bilinear光标这种小图放大显示时插值会糊。改成 Point 立刻锐利。如果还糊检查 Compression 是不是被设成了 Normal Quality改成 None。热点偏移排第二。典型现象是我明明把热点设成笔尖了画出来的线还是偏。原因几乎都是坐标系搞反你以为 (0,0) 是左上角实际 Unity 是左下角。一张 32x32 图笔尖在左上角正确热点是(0, 32)而不是(0, 0)。用 3.2 节的比例方法可以规避。光标尺寸不对先看 Max Size。如果你导入 128x128 光标但 Max Size 是 64Unity 会缩到 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 节三步验证。顺序别乱乱了就容易在到底是贴图问题还是代码问题之间来回猜。
阅读完成 · 觉得有帮助？
