在 Unity 中设置、诊断和修复像素完美 2D…

适用于 Unity 2D 像素画或复古风格项目，需要在 URP 或 Built-in 管线下配置、排查和修复像素完美渲染问题。

适用场景

解决思路

1. 先调用 DetectPipeline()（references/pipeline-detection.cs）检测当前项目使用 URP 还是 Built-in，再分支处理设置、诊断和修复。
2. 不要在一个 URP 项目中安装 com.unity.2d.pixel-perfect。
3. URP 使用 UnityEngine.Rendering.Universal.PixelPerfectCamera，Built-in 使用 UnityEngine.U2D.PixelPerfectCamera；两者组件不可互换。
4. URP 的 PixelPerfectCamera 内置于 URP，无需额外安装；Built-in 需要 com.unity.2d.pixel-perfect v6.0.0+。
5. 注意 API 风格差异：URP 用枚举 gridSnapping、cropFrame；Built-in 用布尔 pixelSnapping、upscaleRT、cropFrameX/Y。
6. Built-in 独立包会安装到 Runtime/ 文件夹，但 asmdef 的 “name” 字段是 Unity.2D.PixelPerfect，没有 Runtime 后缀。
7. HDRP 不支持 Pixel Perfect Camera，改用 HDRP fallback 方案。
8. 始终先诊断再修改；报告发现的问题，只修复已损坏的部分。
9. 默认作用域为当前场景；只有用户明确要求时才全项目扫描。
10. Sprite 导入设置：所有范围内精灵的 Filter Mode 设为 Point (no filter)。
11. Sprite 导入设置：禁用 Mip Maps。
12. Sprite 导入设置：Compression 设为 None / Uncompressed。
13. Sprite 导入设置：确保场景内所有精灵的 PPU 一致。
14. Sprite 导入设置：Sprite pivots 设为 Custom / Pixels 模式；奇数尺寸精灵（如 15×15）使用 center pivot 会落在 7.5px，导致 0.5px 错位。
15. 用 references/sprite-settings.cs 中的 GetImporter() 和 FixSpriteImportSettings() 读取或修复精灵导入设置。
16. 编辑器吸附设置：所有轴 Grid Size = 1 / assetsPPU（例如 PPU 16 -> 0.0625，PPU 100 -> 0.01）。
17. 编辑器吸附设置：在 Grid and Snap overlay 中启用 Grid Snapping。
18. 要吸附已有 GameObject：选中它们 -> Align Selected -> All Axes。
19. 相机设置：Camera projection = Orthographic。
20. 相机设置：存在 Pixel Perfect Camera 组件，且类型与渲染管线匹配。
21. 相机设置：allowHDR、allowMSAA、allowDynamicResolution 全部设为 false。
22. 相机设置：Scene view 中相机 gizmo 显示两个绿色包围框——实线为可见区域，虚线为参考分辨率。
23. 用 references/camera-setup-urp.cs 完成完整的 URP 相机 + PP Camera 配置。
24. 用 references/camera-setup-builtin.cs 完成 Built-in 独立配置。
25. 项目质量设置：Quality Settings 中 Anti-Aliasing = 0。
26. 项目质量设置：Anisotropic Filtering = Disabled。
27. 编写或审查相机设置代码时，阅读 references/api-reference.md 中的完整属性/方法表、GridSnapping 和 CropFrame 枚举值及推荐配置。
28. GridSnapping 取值：None、PixelSnapping（标准）、UpscaleRenderTexture（真实低分辨率；与后处理和 UI 文本不兼容）。
29. CropFrame 取值：None、Pillarbox、Letterbox、Windowbox（最安全默认值）、StretchFill。
30. 在制作任何资源前先选择参考分辨率，资源生产开始后绝不再改。
31. 参考分辨率与整数倍缩放：320×180 对应 1080p 6×、1440p 8×、4K 12×；480×270 对应 4×、~5.3×、8×；640×360 对应 3×、4×、6×。
32. 320×180 是最安全的通用选择。
33. 对于没有整数倍适配的屏幕（如 1366×768），使用 cropFrame = Windowbox 添加黑边，而不是拉伸到分数缩放。
34. 迁移症状：URP 项目误用 Built-in 独立组件时，因独立组件含 ENABLE_URP 条件代码，症状较隐蔽。
35. 迁移：若 DetectPipeline() 返回 URP 但相机上有 UnityEngine.U2D.PixelPerfectCamera，移除 com.unity.2d.pixel-perfect。
36. 迁移：从每个相机移除 UnityEngine.U2D.PixelPerfectCamera。
37. 迁移：添加 UnityEngine.Rendering.Universal.PixelPerfectCamera。
38. 迁移：重新配置——布尔 pixelSnapping、upscaleRT、cropFrameX/Y 改为枚举 gridSnapping、cropFrame。
39. 迁移检测代码见 references/pipeline-detection.cs 底部。
40. 旧 URP 命名空间问题：若编译器报错引用 UnityEngine.Experimental.Rendering.Universal，把 using UnityEngine.Experimental.Rendering.Universal; 替换为 using UnityEngine.Rendering.Universal;。
41. 旧 URP 命名空间问题：更新所有程序集限定类型字符串；[MovedFrom] 属性会自动处理序列化，GameObject 上的组件可在升级后保留。
42. 模糊精灵修复：把范围内所有精灵 Filter Mode 设为 Point，禁用 Mip Maps，并在 Quality Settings 中禁用 AA。
43. Tilemap 瓦片间隙排查 1：若使用了 Sprite Atlas，在 Editor settings 启用 Sprite Packer Mode；在图集上设置 Padding ≥ 4 并关闭 Tight Packing。
44. Tilemap 瓦片间隙排查 2：在 tileset 纹理和图集上禁用 Generate Mip Maps。
45. Tilemap 瓦片间隙排查 3：把 AA 设为 0，并关闭相机上的 MSAA。
46. Tilemap 瓦片间隙排查 4：Compression 设为 None，使用 RGBA 32-bit uncompressed。
47. Tilemap 瓦片间隙排查 5：确保所有 tile 精灵尺寸为偶数像素；奇数尺寸会导致 0.5px 网格偏移。
48. Tilemap 瓦片间隙排查 6：PPU = tile 像素宽度（16×16 -> PPU 16）；PPU 不匹配会留下物理间隙。
49. Tilemap 瓦片间隙排查 7：若以上都通过且仅在相机移动时出现间隙，使用 PP Camera pixel snapping；不要使用 cellGap = -0.01f。
50. 避免使用负 cell gap 或 PPU = 31.99 之类 workaround，它们在相机移动时会失效。
51. Cinemachine 冲突原因：Cinemachine 和 Pixel Perfect Camera 每帧都写入 orthographic size。
52. Cinemachine 冲突修复：在每个 Virtual Camera 的 Add Extension 下拉菜单中添加 CinemachinePixelPerfect 扩展。
53. Cinemachine 冲突修复：不要通过代码 AddComponent 添加该扩展。
54. Cinemachine 已知限制：虚拟相机之间的混合过渡期间不是像素完美。
55. Cinemachine 已知限制：UpscaleRenderTexture 会减少有效的像素完美正交尺寸，可能导致取景偏离。
56. Cinemachine 已知限制：Target Group + Framing Transposer 会导致可见卡顿，且无修复方案。
57. upscaleRT 后处理模糊原因：后处理在 PP Camera 放大 render texture 之后运行。
58. upscaleRT 后处理模糊简单修复：禁用 upscaleRT，让后处理在原生屏幕分辨率运行。
59. upscaleRT 后处理模糊高级修复（Unity 6 URP）：在 RenderPassEvent2D.AfterRenderingPostProcessing 注入 ScriptableRendererFeature2D。
60. 高级修复必须使用 2D 专用基类；ScriptableRendererFeature（3D 基类）在 URP 2D renderer 中会被静默忽略。
61. upscaleRT 下 UI 文本模糊：已知 Unity bug，官方拒绝修复（到 Unity 6/2025 仍存在）。
62. UI 文本模糊根因 A：Canvas 渲染进低分辨率缓冲并随场景一起放大。
63. UI 文本模糊根因 B：TMP 的 SDF gradient threshold 在低参考分辨率下校准错误。
64. UI 文本模糊修复 1（最可靠）：Canvas 使用 Screen Space - Overlay，绕过相机并在原生分辨率渲染。
65. UI 文本模糊修复 2：使用专用 UI 相机且不挂 PP Camera 组件，模式为 Screen Space - Camera。
66. UI 文本模糊修复 3（仅 Unity 6）：Font Material -> Debug Settings -> Sharpness = 1，缓解根因 B，不解决根因 A。
67. 物理/渲染不同步微卡顿原因：物理按固定时间步运行，插值位置产生分数值，每帧吸附到不同像素。
68. 物理/渲染不同步微卡顿修复：在物理驱动精灵上启用 Rigidbody2D.interpolation = RigidbodyInterpolation2D.Interpolate。
69. 物理/渲染不同步微卡顿修复：设置 Time.fixedDeltaTime = 1f / 60f 以匹配目标帧率。
70. 物理/渲染不同步微卡顿修复：相机跟踪放在 LateUpdate，不要放在 FixedUpdate。
71. 非整数缩放/像素抽稀原因：屏幕分辨率不是参考分辨率的干净整数倍。
72. 非整数缩放/像素抽稀修复：选择上面表格中的参考分辨率。
73. 非整数缩放/像素抽稀修复：没有整数适配时使用 cropFrame = Windowbox。
74. 缺少 URP 2D Renderer 修复：通过 Assets > Create > Rendering > URP 2D Renderer Data 创建。
75. 缺少 URP 2D Renderer 修复：把它分配给 URP Asset 的 Renderer List。
76. 缺少 URP 2D Renderer 修复：要求 com.unity.render-pipelines.universal 12.0+。
77. HDRP fallback：Pixel Perfect Camera 在 HDRP 中不受支持。
78. HDRP fallback（Built-in / Unity 5.x）：使用 RenderTexture + Graphics.Blit，并设置 FilterMode.Point。
79. HDRP fallback（Unity 6 URP）：使用 ScriptableRendererFeature2D + ScriptableRenderPass2D，在 RenderPassEvent2D.AfterRendering 通过 AddRasterRenderPass 注入。
80. HDRP fallback（Unity 6 URP）注意：OnRenderImage 和 Graphics.Blit 与 Unity 6 的 render graph 不兼容。

适用边界 · 注意事项

• HD 2D 或高分辨率 2D 游戏——像素吸附和点过滤会让平滑美术看起来错误。
• 仅 UI 的场景——应使用 Canvas Scaler。
• HDRP 项目——不支持 Pixel Perfect Camera。