简介 #
本文档汇总 SmartChart 使用过程中的常见问题与解答(FAQ),涵盖安装启动、依赖库、数据集、图形配置等方面的典型问题及解决方案。
问题分类速查 #
| 分类 | 内容 |
|---|---|
| 安装启动类 | 端口占用、命令找不到、密码重置 |
| 依赖库类 | urllib3 版本冲突 |
| 数据集类 | 数据不更新、参数联动失效 |
| 图形类 | 图形空白/不显示 |
| 模板类 | 占位显示成源码、发布后不生效、界面还是旧的 |
常见问题 FAQ #
安装启动类 #
Q: 启动报错"以一种访问权限不允许的方式做了一个访问套接字的尝试"
Windows 中常见问题,端口被占用(酷狗音乐等软件会占用8000端口):
netstat -ano|findstr 8000 # 找到占用的进程号
taskkill /pid 进程号 /F # 强制终止进程
也可以换一个端口启动:smartchart runserver 0.0.0.0:8001 --insecure --noreload
Q: 输入命令找不到 smartchart
检查是否安装了多个 Python 环境导致环境变量冲突。可以:
- 卸载其中一个 Python 环境
- 或直接用完整路径运行:
python -m smart_chart
Q: 无法安装 pip
安装 Python 时未勾选"Add to PATH",请:
- 重新安装 Python(勾选 Add to PATH)
- 或手动将 Python 安装目录下的
Scripts文件夹加入系统 PATH
Q: Mac 安装后各种问题(找不到命令等)
最大可能是系统 /Library/Developer/CommandLineTools 下残留了旧的 Python 3,与新安装的冲突:
# 先卸载旧版本
sudo rm -rf /Library/Developer/CommandLineTools
sudo rm -f /usr/bin/python3
# 再按文档重新安装 Python
确认完全卸载:命令行输入 python3 和 pip3,提示找不到命令才算干净。
Q: 忘记管理员密码
smartchart changepassword 你的用户名
依赖库类 #
Q: 安装时提示 urllib3 版本冲突
报错类似:<PACKAGE> depends on urllib3==2.0.0 时:
pip install urllib3==1.26.15
数据集类 #
Q: 数据集保存后图形数据没有更新
常见原因:
- 数据集设置了缓存时间,需等待缓存过期或在 URL 中加
&refresh=Y强制刷新 - 数据集为懒加载模式,需要手动触发
ds_refresh() - SQL 查询本身没有返回新数据
Q: 参数联动后数据不变化
可能原因:
- SQL 中的参数名(
$参数名)与前端传的参数名不一致(注意大小写) - 数据集设置了缓存,带参数的数据集应将缓存时间设为 0
模板类 #
Q: 模板里写了 {{div_list.0}},页面上却直接把这段源码显示出来了
占位符没有被模板引擎渲染,常见原因:
- 骨架模板用的是
baselite,它没有包{% autoescape off %},占位输出的 HTML 会被转义成文本;换成base/basevue等骨架,或在模板里用{% autoescape off %}...{% endautoescape %}包住占位 - 模板没有
{% extends "echart/base.html" %},或占位写在了head区块而不是body区块 - 序号写错:模板里没有这个序号的图形时也会输出空内容
Q: 改完模板保存了,但访客看到的还是旧页面
「保存」只更新开发草稿,「发布」才更新线上模板。点顶栏「发布」并在发布面板里确认一次即可,详见 模板上线。
Q: 编辑器里没有看到新界面(属性面板、脚本页、版本页等)
前端静态资源带版本号,升级后第一次访问需要强制刷新(Ctrl/⌘ + Shift + R)清掉旧缓存。
Q: 一个图形在页面上出现了两次
模板同时保留了自动 DIV 循环({% for div in div_list %}{{div}}{% endfor %})和单独的 {{div_list.N}} 占位。两种方式只能选一种,详见
快捷开发。
图形类 #
Q: 图形空白/不显示
检查步骤:
- 打开浏览器 F12,查看 Console 是否有 JS 报错
- 检查数据集是否有数据(在数据集编辑器执行查询)
- 检查图形代码中的
__dataset__取值是否正确 - 如果是多段查询,检查
dataset.df0的格式是否正确