piccolo_admin 当前仅兼容 piccolo 1.x，不支持 2.x：需降级 piccolo、修正字段定义（如显式指定 related_name）、使用旧版迁移命令；同时须安装 piccolo_api 及依赖，正确注册模型并配置静态资源路由。
piccolo_admin 要求 Piccolo 1.x，不兼容 Piccolo 2.x 的 Table 定义
Piccolo 2.x 彻底重构了 Table 基类和字段声明方式，而 piccolo_admin 当前（v1.8.x）仍基于 Piccolo 1.x 的元数据反射逻辑。直接把 Piccolo 2.x 的模型丢给 piccolo_admin，会报 AttributeError: 'Model' object has no attribute '_meta' 或字段识别失败。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 确认版本：运行
pip show piccolo piccolo_admin，若piccolo显示 2.x，则必须降级——pip install "piccolo==1.11.3"（当前最稳定的 1.x 版本） - 字段定义别用
ForeignKey(null=True)这类 2.x 写法；Piccolo 1.x 要写成ForeignKey(null=True, related_name="...")，且related_name必须显式指定 - 迁移命令也得换：Piccolo 1.x 用
piccolo migrations forwards app_name，不是piccolo migrations migrate
admin 启动时报 No module named 'piccolo_api'
piccolo_admin 是个独立包，但依赖 piccolo_api 提供的认证、序列化等基础能力，而它不会被自动安装。很多人只装了 piccolo_admin 就跑，结果卡在 import 阶段。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 必须一起安装：
pip install piccolo_admin piccolo_api（顺序无关） - 如果用了 JWT 认证，还需额外装
python-jose[cryptography]，否则启动时提示ImportError: No module named 'jose' - 检查
sys.path是否干净：虚拟环境中混装 conda 和 pip 包容易导致 import 冲突，建议全新 venv + pip install
自定义 admin 页面时，register_table 不生效
常见于想把某个 Table 加到 admin 但页面不显示，或者字段顺序/类型没按预期渲染。根本原因通常是注册时机不对，或模型未被正确导入。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 确保
register_table在app.py（或启动文件）中调用，且在piccolo_admin的App实例创建之后——不能在模型定义文件里就调用 - 表名必须传真实类对象，不是字符串：
register_table(MyUser)✅，register_table("MyUser")❌ - 如果字段用了
BaseField子类但没实现to_dict方法，admin 渲染会静默跳过该字段；简单起见，优先用Varchar、Integer等内置字段
部署后 admin 静态资源 404（CSS/JS 加载失败）
piccolo_admin 把前端资源打包进 Python 包内，通过 ASGI 应用动态 serve。但某些 ASGI 服务器（如 Uvicorn 单独运行、或 Nginx 反代配置不当）会拦截 /static/ 路径，导致样式崩坏。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 启动时加
--static-url /static/参数，并确认 ASGI server 没有重写该路径（比如 Nginx 的location /static规则要删掉或设为 proxy_pass 到 admin 服务） - 检查响应头：访问
/static/app.css，应返回 200 +content-type: text/css；若返回 404，大概率是 ASGI 层没挂载静态路由——确认你用的是piccolo_admin.app.PiccoloAdmin实例，不是裸的 Starlette App - 开发阶段可临时用
piccolo_admin --reload，它内置了 static 文件服务；生产环境别依赖这个，要用反代或单独托管静态文件
真正麻烦的是混合使用 Piccolo 1.x 模型和现代异步 Web 框架（比如 FastAPI），此时 ORM 同步阻塞调用会拖慢整个 event loop。这点文档几乎不提，但线上一压测就暴露。
