最近群里聊青龙脚本库的人越来越多，新面孔一茬接一茬。很多人刚接触的时候，看教程觉得挺简单，不就是拉个库、装个依赖、跑个定时任务嘛。结果真上手了，问题一个接一个往外冒。有的卡在环境变量上，有的被依赖报错折腾到半夜，还有的脚本跑着跑着就不动了，连日志都看不出毛病。我自己也是从那个阶段过来的，踩过的坑不比谁少。索性把论坛里反复出现的问题捋一捋，挑出那些问得最多、最容易把人绕进去的，挨个说说怎么解决。

一、青龙面板装好了，脚本库也拉了，为什么任务列表是空的？

这是新人问得最多的一个问题，没有之一。面板能打开，账号也登进去了，按照教程在“脚本管理”里填了仓库地址，点了拉取，提示也显示成功了，可切到“定时任务”一看，空空如也。这时候别急着怀疑人生，先检查两个地方。

第一个是仓库地址后面有没有加分支名。很多教程给的地址是类似 http://github.com/xxx/xxx.git 这种格式，但青龙默认拉的是主分支。有些脚本库的主分支里只有 README 和说明文件，真正的脚本藏在 main 或者 master 之外的分支里，比如 dev、release 之类。你需要在仓库地址后面加上 #分支名，比如 http://github.com/xxx/xxx.git#main，这样拉下来的才是带脚本的那份。

第二个是拉取方式选错了。青龙的脚本管理里有两个选项，一个是“拉取仓库”，一个是“添加脚本”。很多人把仓库地址填到了“添加脚本”里，那当然只会在脚本目录下生成一个孤零零的文件，定时任务里自然看不到东西。正确的做法是在“拉取仓库”里操作，填好地址、分支、定时规则（这个可以后面再改），点确定，等它跑完，再去定时任务里刷新一下，一般就出来了。

还有一种情况是仓库本身的问题。有些库作者把脚本放在子目录里，青龙拉取的时候默认只拉根目录，子目录里的东西不会自动展开。这时候你得手动进脚本目录看看，如果发现脚本都在某个文件夹里，那就得在定时任务里手动指定路径，或者干脆把那个子目录的脚本复制到根目录下。虽然麻烦点，但总比干瞪眼强。

二、依赖装不上，报错五花八门，到底该信哪个？

依赖问题是第二大坑。青龙跑脚本靠的是 Node.js 和 Python 环境，脚本里用到什么库，就得提前装好。但问题是，很多脚本作者只写了个 require('xxx') 或者 import xxx，没告诉你具体要装哪个版本。你照着报错信息去搜，搜出来的答案五花八门，有的说 npm install xxx，有的说 pip install xxx，还有的说要装 xxx@1.2.3 特定版本，试了一圈还是报错。

我的经验是，先看报错关键词。如果是 Cannot find module 'xxx'，那就是缺 Node.js 模块，去青龙的“依赖管理”里，选“NodeJs”类型，名称填 xxx，然后点安装。注意这里有个坑：青龙的依赖管理装的是全局包，但有些脚本是在子目录里跑的，它可能读不到全局的 node_modules。这时候你得进到脚本所在目录，手动执行 npm install xxx，或者把全局的 node_modules 路径加到环境变量里。

如果是 ModuleNotFoundError: No module named 'xxx'，那就是缺 Python 模块，同样在依赖管理里选“Python3”，名称填 xxx，点安装。但 Python 的坑更深，因为有些库需要编译，青龙的容器里不一定有编译环境。比如 lxml、cryptography 这类库，直接 pip install 可能会报 gcc 找不到或者 Python.h 缺失。遇到这种情况，要么换一个不需要编译的版本，要么进容器手动装编译工具，比如 apt-get install gcc python3-dev，然后再装库。不过青龙容器重启后这些手动装的东西可能会丢，所以最好把安装命令写进 extra.sh 或者自定义启动脚本里。

还有一种报错是版本冲突。比如脚本 A 需要 requests==2.25.0，脚本 B 需要 requests==2.28.0，你装了一个另一个就报错。这种问题基本无解，只能看哪个脚本更重要，或者找找有没有兼容的版本。实在不行就把两个脚本分开跑，用不同的容器或者不同的 Python 虚拟环境。虽然麻烦，但比天天看报错强。

三、环境变量到底怎么填？为什么填了还是提示未定义？

环境变量是青龙的核心，也是新人最容易迷糊的地方。很多脚本要求你填 COOKIE、TOKEN、API_KEY 之类的变量，你在面板的“环境变量”里加了，名称和值都填了，可跑起来还是提示 undefined 或者 未找到变量。这时候先别急着骂脚本，检查下面几个点。

第一，变量名大小写。有些脚本作者写的是 cookie，有些写的是 COOKIE，还有的写的是 Cookie。青龙的环境变量是区分大小写的，你填的时候必须和脚本里读的一模一样。怎么确认？去看脚本源码，搜 process.env 或者 os.environ，看看它到底读的是哪个名字。别嫌麻烦，这一步能省掉你后面几个小时的排查时间。

第二，变量值有没有多余的空格或者换行。从网页上复制 Cookie 的时候，很容易把末尾的空格或者换行也复制进去。青龙虽然会做一些处理，但有些脚本对格式要求很严，多一个空格就解析失败。建议填完之后把光标移到值的末尾，按几下删除键，确保没有隐藏字符。如果是多账号，用 & 或者 \n 分隔，具体看脚本说明，别自己瞎猜。

第三，变量有没有生效。青龙的环境变量修改后，需要重启容器或者重新加载配置才会生效。有些版本的面板里有个“重启”按钮，点一下就行。如果没有，就去容器里执行 docker restart qinglong（假设容器名是 qinglong）。重启之后再去跑脚本，一般就没问题了。

第四，脚本有没有从环境变量里读。有些脚本虽然文档里写了要填环境变量，但代码里其实是从配置文件或者数据库里读的。这种情况你环境变量填得再对也没用，得去看脚本的实际逻辑。如果发现它读的是 config.json 或者 data.db，那就得去改对应的文件，而不是在青龙面板里折腾。

四、定时任务跑了，但日志里全是乱码或者空白的，怎么回事？

日志是排查问题的关键，但有时候日志本身就不靠谱。你点开某个任务的日志，发现要么是乱码，要么是空白一片，要么只有几行 开始执行 和 执行结束，中间啥也没有。这种情况一般有几种原因。

一是编码问题。青龙默认用 UTF-8 编码，但有些脚本输出的是 GBK 或者其他编码，尤其是从 Windows 环境迁移过来的脚本。这时候日志里就会出现乱码。解决办法是在脚本开头加上 # -*- coding: utf-8 -*-（Python）或者 process.stdout.setEncoding('utf8')（Node.js），强制统一编码。如果脚本本身没法改，那就只能忍了，或者把日志导出来用其他工具转码看。

二是脚本没有输出。有些脚本写得比较“安静”，跑完了也不打印任何东西，只在出错的时候才输出。这种脚本你光看日志是看不出它到底跑没跑的。这时候可以去“定时任务”里看它的执行状态，如果是“成功”那就说明跑完了，如果是“失败”那就得去查错误日志。另外，有些脚本会把结果写到文件里，比如 log.txt 或者 result.json，你可以去脚本目录下翻翻看。

三是日志被截断了。青龙的日志默认只保留最近多少行，如果脚本输出特别多，前面的内容就会被冲掉。你可以在面板的设置里调整日志保留行数，或者把脚本的输出重定向到文件里，比如 python xxx.py > /ql/logs/xxx.log 2>&1，这样就能完整保留了。

四是任务根本没跑起来。有时候你看到日志里有“开始执行”，但后面就没有了，那可能是脚本在初始化阶段就卡住了，比如网络请求超时、依赖加载失败、权限不足等等。这时候得去容器里手动跑一遍脚本，看看具体卡在哪一步。命令一般是 docker exec -it qinglong bash，进去之后 cd /ql/scripts/xxx，然后 python xxx.py 或者 node xxx.js，看它报什么错。

五、脚本跑着跑着就停了，也没有报错，是什么原因？

这个问题比较玄学，但也不是无迹可寻。脚本跑一半停住，通常有几种可能。

一是网络请求卡住了。很多脚本需要访问外部 API，如果对方服务器响应慢或者直接不响应，脚本就会不断等，直到超时。但有些脚本没有设置超时时间，就会不断卡在那里。解决办法是在脚本里加上超时设置，比如 Python 的 requests.get(url, timeout=10)，Node.js 的 axios.get(url, { timeout: 10000 })。如果脚本没法改，那就只能看运气了，或者换个时间段跑。

二是内存或者 CPU 不够。青龙容器默认的资源限制可能比较低，如果脚本处理的数据量比较大，或者同时跑多个任务，就容易把资源耗尽。这时候容器可能不会直接崩溃，但脚本会变得极慢甚至卡死。你可以去宿主机的终端里执行 docker stats，看看青龙容器的 CPU 和内存占用。如果不断很高，那就得考虑升级配置或者减少同时运行的任务数。

三是脚本被系统杀掉了。有些脚本会无限循环或者占用大量资源，青龙或者宿主机的系统可能会把它当成异常进程杀掉。这时候日志里通常不会有明显报错，但任务状态会变成“失败”或者“未知”。解决办法是优化脚本逻辑，避免死循环，或者给脚本加上退出条件。

四是定时任务冲突。如果你设置了多个任务在同一时间跑，它们可能会互相抢资源，导致某个任务被挤掉。这时候可以错开时间，比如一个任务设成 0 0 * * *，另一个设成 5 0 * * *，间隔几分钟，让它们排队跑。

六、更新脚本库之后，原来的配置全没了，怎么避免？

这个问题也挺常见。你拉了一个脚本库，辛辛苦苦填了一堆环境变量，跑得好好的。结果某天作者更新了库，你手贱点了“更新”，然后发现原来的脚本被覆盖了，配置文件也没了，环境变量虽然还在，但脚本读不到了。这时候想死的心都有。

避免的方法其实很简单：第一，重要的配置文件不要放在脚本目录里。比如 config.json、data.db 这些，尽量放在脚本目录外面，比如 /ql/data/ 下面，然后在脚本里用绝对路径去读。这样即使脚本被覆盖，配置文件还在。

第二，环境变量尽量用青龙面板来管理，不要写在脚本里。青龙的环境变量是独立存储的，更新脚本不会影响它们。但前提是脚本得从环境变量里读，而不是从文件里读。如果脚本作者没写这个逻辑，你可以自己改一下，把读文件改成读环境变量。

第三，更新之前先备份。青龙的脚本目录一般是 /ql/scripts/，你可以把它整个打包下载下来，或者用 cp -r 复制一份。更新之后如果发现不对劲，再把备份还原回去。虽然土了点，但管用。

第四，有些脚本库支持“保留配置”的更新方式，比如在拉取的时候勾选“不覆盖已存在的文件”。青龙的拉取仓库界面里有个选项叫“忽略已存在文件”，勾上它，更新的时候就不会覆盖你改过的脚本。但这样也有个问题，就是作者的新功能你可能用不上。所以得权衡一下，是保配置还是追新版。

七、为什么别人的脚本跑得好好的，到我这儿就各种报错？

这个问题其实不怪你，也不怪脚本，怪的是环境差异。每个人的青龙版本、系统架构、网络环境、依赖版本都不一样，同一个脚本在别人的机器上跑得飞起，到你这儿可能就各种水土不服。

常见的差异有：青龙版本不同。有些脚本用了新版本的 API，你的青龙版本太老，不支持，就会报错。这时候要么升级青龙，要么找适配旧版本的脚本。系统架构不同。ARM 架构的机器（比如树莓派、某些 NAS）和 x86 架构的机器，有些二进制依赖是不通用的。你装依赖的时候得选对架构的版本，或者用源码编译。网络环境不同。有些脚本需要访问外网，如果你的网络被墙了或者 DNS 有问题，就会连接超时。这时候得挂代理或者换 DNS。依赖版本不同。前面说过，版本冲突是个大坑，同一个库不同版本可能行为完全不一样。这时候得看脚本作者推荐哪个版本，或者自己慢慢试。

遇到这种情况，别急着放弃。先去论坛搜搜有没有人遇到类似问题，或者直接问作者。如果作者不搭理，那就自己慢慢排查。从报错信息入手，一行一行看，总能找到线索。实在不行就换个脚本，条条大路通罗马，没必要在一棵树上吊死。

八、青龙面板打不开了，怎么办？

面板打不开是最让人慌的，因为啥都干不了。这时候先别急，按顺序排查。

第一步，看容器还在不在。去宿主机的终端里执行 docker ps -a，看看青龙容器的状态。如果是 Exited，那就说明容器挂了，得看日志找原因。执行 docker logs qinglong，看看最后几行报了什么错。常见的原因有端口被占用、配置文件损坏、磁盘满了等等。

第二步，如果是端口被占用，那就改个端口。青龙默认用的是 5700，你可以改成 5701 或者其他没被占用的端口。改完之后重启容器，再用新端口访问。

第三步，如果是配置文件损坏，那就得进容器里修复。执行 docker exec -it qinglong bash，进去之后检查 /ql/config/ 目录下的文件，看看有没有异常。如果搞不定，就把整个 /ql 目录备份一下，然后重新拉一个容器，把备份的数据导进去。

第四步，如果是磁盘满了，那就清理一下。执行 df -h 看看哪个分区满了，然后删掉一些不用的日志、缓存、旧镜像。青龙的日志目录一般在 /ql/log/，可以定期清理。Docker 的镜像和容器也可以用 docker system prune 清理。

第五步，如果以上都搞不定，那就重装吧。把 /ql 目录备份好，然后删掉容器和镜像，重新拉一个最新的青龙。装好之后把备份的数据导进去，环境变量和脚本都还在，损失不大。

说到底，青龙脚本库这东西，门槛不高但坑不少。新人刚上手的时候，遇到问题别慌，多搜多问多试。论坛里那些常见问题，其实翻来覆去就那么几个，把上面这些搞明白了，基本上能解决百分之八十的麻烦。剩下的百分之二十，要么是脚本本身的问题，要么是环境太特殊，那就只能具体问题具体分析了。玩青龙就是个不断踩坑不断填坑的过程，踩得多了，自然就成老手了。