title: VRChat 模型常见问题排查
created: 2026-05-01
updated: 2026-05-01
type: reference
tags: [vrchat, troubleshooting, debug, fix]
🔧 VRChat 模型常见问题排查
模型全黑、贴图错位、物理抖动、穿模等问题的排查与解决方案。
1. 模型全黑 🖤
| 可能原因 |
排查方法 |
解决方案 |
| 法线朝内 |
场景中添加 Directional Light 观察阴影方向 |
Inspector 勾选 Fix Normals，或 Blender 中翻转法线 |
| 未分配 Light Probe |
检查 Avatar 是否在 Light Probe 范围内 |
场景添加 Light Probe Group |
| Albedo 颜色为黑/灰 |
检查材质 Albedo Color |
设为白色 #FFFFFF |
| 法线贴图误开 sRGB |
检查 Normal 贴图的 sRGB 设置 |
Normal 贴图取消 sRGB 勾选 |
2. 贴图错位/拉伸 🔀
| 可能原因 |
排查方法 |
解决方案 |
| UV Tiling/Offset 未重置 |
检查材质面板 Tiling/Offset |
Tiling 设为 1,1，Offset 设为 0,0 |
| 纹理图集后未重烘焙 |
对比图集前后的 UV 布局 |
使用 Mesh Baker 重新投影烘焙 |
| Wrap Mode 设置错误 |
检查贴图 Wrap Mode |
边缘接缝处设 Wrap Mode: Clamp |
| UV 范围超出 0-1 |
检查 UV 坐标范围 |
确认 UV 在 0-1 范围内 |
3. Alpha 裁剪异常/闪烁 ✂️
| 可能原因 |
排查方法 |
解决方案 |
| Render Queue 错误 |
检查材质 Render Queue 值 |
Cutout = 2450 (AlphaTest)，透明 = 3000 (Transparent) |
| Shadow Caster Pass 缺失 |
检查 Shader 是否包含 ShadowCaster |
确保 Shader 包含 Pass { Tags {"LightMode"="ShadowCaster"} } |
| 透明混合排序混乱 |
多个透明物体重叠 |
将薄透明部件拆分为独立材质 |
4. PhysBone 问题
骨骼爆炸/乱飞 💥
| 原因 |
解决 |
| Pull 过低无法拉回 |
提高 Pull 至 0.3+ |
| Spring 过高导致能量累积 |
降低 Spring 至 0.2 以下 |
| 未设置碰撞导致穿透卡死 |
添加对应部位 Collider，设 Radius > 0 |
| ull 至 0.3+ |
|
| Spring 过高导致能量累积 |
降低 Spring 至 0.2 以下 |
| 未设置碰撞导致穿透卡死 |
添加对应部位 Collider，设 Radius > 0 |
| 原因 |
解决 |
| :--- |
:--- |
| Integration Type 误选 Unity |
改为 Stable |
| Spring 与 Stiffness 冲突 |
降低 Spring，提高 Stiffness |
| 多子节点分叉未处理 |
Multi Child Type 改为 Rigid 或拆分独立链 |
严重穿模 👗
| 原因 |
解决 |
| Collider Radius 太小 |
放大 Collider 半径（比网格大 1~2cm） |
| Collision Layers 未勾选 Self |
确保 Self 勾选 |
| 物理链 Limit 过大 |
收紧 Limit Max 角度 |
性能卡顿 🐢
| 原因 |
解决 |
| 物理链过长（>15 骨骼） |
减少末端骨骼或合并 Mesh |
| 碰撞体过多/开启 Environment |
关闭不必要的 Environment 碰撞 |
| Update Type 设为 FixedUpdate |
改回 LateUpdate |
5. 性能问题
帧率低
| 检查项 |
目标值 |
优化方法 |
| Skinned Mesh Renderer 数量 |
≤ 2 (Excellent) |
合并同材质网格 |
| 材质数 |
≤ 2 (Excellent) |
纹理图集 + 材质合并 |
| 贴图内存 |
≤ 16 MB (PC Good) |
压缩贴图、降低分辨率 |
| 骨骼数 |
≤ 75 (PC Excellent) |
删除冗余骨骼 |
| PhysBone 根节点数 |
≤ 10 |
合并同区域物理链 |
内存占用高
| 检查项 |
优化方法 |
| 贴图未压缩 |
使用 BC7 (PC) / ASTC (Quest) |
| 贴图尺寸过大 |
降至 1024 或 2048 |
| 使用 Crunch 压缩 |
禁用 Crunch（Avatar 场景） |
| 过多材质实例 |
合并材质，使用共享材质 |
6. 动画问题
动画不播放
| 原因 |
解决 |
| Animator Controller 未绑定 |
检查 VRC_AvatarDescriptor 的 Playable Layers |
| 参数名不匹配 |
确保 Expression Parameters 与 Animator 中参数名一致 |
| Transition 条件错误 |
检查 Transition 的 Condition 设置 |
手势不响应
| 原因 |
解决 |
| Gesture Layer 未配置 |
确保 Gesture Layer 有 Controller |
| 骨骼未映射到 Humanoid |
重新 Configure Avatar |
| 参数名错误 |
使用标准参数名 GestureLeft/GestureRight |
| troller |
|
| 骨骼未映射到 Humanoid |
重新 Configure Avatar |
| 参数名错误 |
使用标准参数名 GestureLeft/GestureRight |
| 原因 |
解决 |
| :--- |
:--- |
| Lip Sync 模式错误 |
设为 Viseme 或 Jaw Flap |
| BlendShape 权重为 0 |
检查 BlendShape 值范围 |
| Viseme 参数名不匹配 |
设为 Viseme（默认） |
7. 上传问题
上传失败
| 原因 |
解决 |
| Avatar Descriptor 未配置 |
确保 Root 上有 VRC_AvatarDescriptor |
| 骨骼映射不完整 |
重新 Configure Avatar 为 Humanoid |
| Animator 为空 |
至少绑定一个默认 Animator Controller |
| 场景中有多个 Avatar |
只保留一个 Avatar 在场景中 |
上传后在其他客户端显示异常
| 原因 |
解决 |
| 缓存问题 |
让其他玩家使用 /refresh 清除缓存 |
| 平台兼容性 |
Quest 端使用了 PC 专属 Shader |
| 性能降级 |
Avatar 评级过低触发 Fallback |
8. 排查流程图
问题现象
↓
检查 Unity Console 是否有 Error/Warning
↓
├── 有 Error → 根据错误信息定位
├── 有 Warning → 评估是否需要修复
└── 无 → 检查以下维度:
├── 渲染 → 材质/贴图/Shader
├── 物理 → PhysBone/Collider
├── 动画 → Animator/Parameters
└── 性能 → DrawCall/内存/骨骼
💡 排查原则: 先检查最简单的可能原因（如 sRGB 设置、参数名匹配），再逐步深入。80% 的问题都是配置错误而非代码 bug。