Unity 鼠标指针贴图设置：用 Cursor.SetCursor 与 Texture2D 打造自定义光标

1. Unity 鼠标指针贴图设置从默认箭头到自定义光标的完整落地Unity 里换鼠标指针这件事说简单也简单一行Cursor.SetCursor就能改说坑多也是真多导入设置没改、热点对不齐、CursorMode选错都会让你盯着屏幕怀疑人生。这篇就围绕Cursor.SetCursor与Texture2D把「鼠标指针贴图」从导入到生效的完整链路讲清楚覆盖CursorMode选择、热点对齐、导入设置以及一套可以直接复制的配置代码和验证步骤。适合谁看正在做 Unity 游戏或工具类项目、想把默认白色箭头换成自定义光标准星、抓手、魔法棒、画笔等的开发者尤其是刚接触Cursor.SetCursor、被「贴图不显示」「热点偏移」「光标糊成一团」卡住的同学。读完你能拿到一份可运行的 C# 脚本、一套导入参数对照表、一份常见报错排查清单以及验证光标是否真的生效的方法。先说结论Unity 换光标的核心就三件事——把图片导入成Texture2D且类型设为Cursor、用Cursor.SetCursor传入贴图和热点、根据平台选对CursorMode。下面按顺序拆。2. 前置准备TaoToken 与工程环境在动手写代码前先把环境和素材准备好。工程侧你需要一个 Unity 项目2020 LTS 及以上都行API 没变素材侧你需要一张准备当光标的 PNG。如果你在开发过程中需要调用大模型来辅助生成光标素材描述、写批处理脚本或者做 AI 相关的工具链可以用 TaoToken 统一管理模型调用入口省得每个服务单独配 Key。TaoToken 官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content它的 API 地址是 https://taotoken.net/api 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你只是想在写代码时让模型帮你解释Cursor.SetCursor的参数可以直接用模型对话页https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。需要生成 API Key 的话在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。注意TaoToken 在这里的角色是「模型调用入口」和 Unity 光标功能本身没有耦合。你完全可以在纯本地、不联网的情况下完成本篇所有光标设置。把它放在前置章节只是方便你在需要 AI 辅助时有个统一入口不要理解成「换光标必须用它」。素材准备的关键点光标图片建议用 32×32 或 64×64 的 PNG背景透明。尺寸太大在某些平台会被强制缩放导致模糊尺寸太小在高分屏上又会糊。热点hotspot就是「鼠标实际点击的那个像素点」比如箭头光标的热点在左上角准星光标的热点在正中心。3. 可复制配置导入设置 Cursor.SetCursor 代码3.1 导入设置把 Texture 类型改成 Cursor很多人第一步就错了——直接把 PNG 拖进工程然后代码里Cursor.SetCursor传进去结果光标不显示或者显示成一块白。原因是 Unity 默认把图片导入成Sprite或Default而Cursor.SetCursor需要的是Texture2D并且导入类型最好设为Cursor。操作路径在 Project 窗口选中图片 → Inspector 顶部Texture Type下拉 → 选Cursor→ 点Apply。改完后关键参数如下参数推荐值说明Texture TypeCursor专为光标准备的导入类型Texture Shape2D光标是二维贴图Alpha Is Transparency勾选保证透明边缘干净不出现黑边Read/Write关闭光标不需要 CPU 读回省内存Filter ModePoint (no filter)像素风光标必选避免模糊CompressionNone 或 High Quality小图建议 None避免压缩噪点Max Size不小于原图防止被强制缩小提示如果你的光标是像素风格Filter Mode一定要选Point (no filter)否则边缘会被插值糊掉。写实风格的光标可以用Bilinear。3.2 核心代码Cursor.SetCursor 三参数Cursor.SetCursor的签名是public static void SetCursor(Texture2D texture, Vector2 hotspot, CursorMode cursorMode);三个参数分别是贴图、热点偏移量、光标模式。热点用像素坐标表示原点在贴图左上角。比如 32×32 的准星热点就是(16, 16)箭头光标热点在(0, 0)。下面是一份可直接挂到空物体上的完整脚本using UnityEngine; public class CustomCursor : MonoBehaviour { [Header(光标贴图)] public Texture2D cursorTexture; [Header(热点像素坐标左上角为原点)] public Vector2 hotspot new Vector2(16, 16); [Header(光标模式)] public CursorMode cursorMode CursorMode.Auto; void Start() { ApplyCursor(); } public void ApplyCursor() { if (cursorTexture null) { Debug.LogWarning(cursorTexture 未赋值保持默认光标); return; } // 关键热点不能超过贴图尺寸否则部分平台会异常 hotspot.x Mathf.Clamp(hotspot.x, 0, cursorTexture.width); hotspot.y Mathf.Clamp(hotspot.y, 0, cursorTexture.height); Cursor.SetCursor(cursorTexture, hotspot, cursorMode); } // 恢复默认光标 public void ResetCursor() { Cursor.SetCursor(null, Vector2.zero, CursorMode.Auto); } }把脚本挂到场景里任意物体上在 Inspector 里把导入好的光标贴图拖到cursorTexture运行即可看到光标变化。3.3 CursorMode 怎么选CursorMode只有两个值但选错会直接导致「光标不显示」模式行为适用场景CursorMode.Auto平台自行决定硬件支持就用硬件光标大多数桌面平台性能最好CursorMode.ForceSoftware强制用软件渲染光标硬件光标不支持大尺寸/特殊格式时实测下来Windows 和 macOS 桌面端用Auto基本没问题如果你用了 128×128 以上的大光标或者在某些 Linux 环境下光标不显示切到ForceSoftware往往能解决。代价是软件光标每帧重绘极端情况下有轻微性能开销但普通项目感知不到。4. 验证请求与成功结果代码挂上、贴图拖好之后怎么确认真的生效了按下面几步验证第一步运行场景把鼠标移到 Game 视图内。如果光标变成了你的贴图说明基础设置成功。注意Scene 视图里的光标不会变只有 Game 视图运行时才会应用Cursor.SetCursor。第二步验证热点是否对齐。用一个热点在正中心的准星光标把鼠标移到某个 UI 按钮正中心点击看按钮是否被触发。如果点击位置和视觉中心有偏移说明热点算错了。热点公式hotspot (贴图宽度 / 2, 贴图高度 / 2)是正中心。第三步验证透明边缘。把光标移到深色和浅色背景交界处观察边缘有没有黑边或白边。有黑边通常是Alpha Is Transparency没勾有白边可能是压缩噪点把Compression设为None。第四步跨分辨率验证。把 Game 视图分辨率从 1080p 切到 720p 再切回观察光标是否被拉伸变形。如果变形检查Max Size是否小于原图尺寸。一个可打印的验证日志方便你在 Console 里确认参数void Start() { ApplyCursor(); Debug.Log($光标已应用: 贴图{cursorTexture?.name}, $尺寸{cursorTexture?.width}x{cursorTexture?.height}, $热点{hotspot}, 模式{cursorMode}); }运行后 Console 输出类似光标已应用: 贴图crosshair, 尺寸32x32, 热点(16.0, 16.0), 模式Auto就说明参数都传对了。5. 本篇常见错误排查下面这些是我在实际项目里踩过的坑按出现频率排序光标完全不显示。最常见原因是贴图导入类型不是Cursor或者Cursor.SetCursor传了null。先确认 Inspector 里Texture Type是Cursor再确认脚本里cursorTexture有赋值。还有一种情况你在Start之前就调用了贴图还没加载完改成Start或延迟一帧。光标显示但热点偏移。热点坐标原点在左上角不是左下角很多人按数学坐标系算就错了。32×32 的图正中心是(16, 16)不是(15, 15)差一个像素在高分屏上肉眼可见。光标模糊/有锯齿。像素风没设Point (no filter)或者Max Size被压到了 64 以下。把Filter Mode改PointMax Size拉到 2048。切换场景后光标恢复默认。Cursor.SetCursor是全局状态但场景切换时如果新场景没有重新调用某些平台会重置。解决办法把光标设置逻辑放到DontDestroyOnLoad的管理器里或者在每个场景的Start里重新调用一次。打包后光标不显示编辑器里正常。检查贴图是否被包含进构建。如果贴图只被脚本引用而没放在Resources或没被场景引用打包时可能被剔除。把贴图放到Resources文件夹或者用[SerializeField]确保被场景引用。ForceSoftware 下光标闪烁。软件光标在某些驱动上会和硬件光标冲突表现为快速闪烁。解决方法是统一用Auto或者确保同一时间只有一个脚本在调Cursor.SetCursor。注意Cursor.SetCursor设置的是全局光标多个脚本同时调用会互相覆盖。如果你的项目有「默认光标 / 悬停光标 / 拖拽光标」多种状态建议用一个CursorManager单例统一管理避免状态打架。6. 继续深入把光标接入你的工具链光标设置本身不复杂难的是把它和你的项目状态机、UI 系统、多平台构建串起来。如果你在写更复杂的编辑器工具或 AI 辅助的开发流程需要模型帮你生成光标状态机代码、批量处理贴图导入参数可以用 TaoToken 的 Coding Plan 做长期编码辅助https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。需要管理多个项目的 Key 时控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。回到 Unity 本身最后给你一个实用技巧把光标贴图的导入设置写成一个AssetPostprocessor这样以后所有放进Assets/Cursors/的图片都会自动设成Cursor类型、Point过滤、Alpha Is Transparency省得每张图手动改。这才是「一次配置、长期省事」的做法。using UnityEditor; public class CursorTexturePostprocessor : AssetPostprocessor { void OnPreprocessTexture() { if (!assetPath.Contains(/Cursors/)) return; TextureImporter importer (TextureImporter)assetImporter; importer.textureType TextureImporterType.Cursor; importer.alphaIsTransparency true; importer.filterMode FilterMode.Point; importer.textureCompression TextureImporterCompression.Uncompressed; } }把这段放进Editor文件夹之后往Assets/Cursors/里丢图导入参数自动就对了。光标设置这条链路从导入到生效到这里就闭环了。