QPython 环境变量与模块导入——让自定义包可被正确引用

Python 模块导入基础

Python 的 import 语句按一个叫 sys.path 的路径列表来搜索模块。QPython 的解释器启动时会预设好一些路径：内置标准库、已安装的第三方包目录、当前工作目录。

>>> import sys
>>> print(sys.path)
['', '/data/data/org.qpython.qpy/files/lib/python3.x', ...]

列表中第一个空字符串 '' 代表当前工作目录，这就是为什么当前目录下的 .py 文件可以直接 import。

导入自定义模块的常见坑

场景一：脚本和模块不在同一目录

假设你的主脚本在 scripts/ 下，但想导入 modules/ 目录下的自定义模块：

import sys
sys.path.insert(0, "modules")  # 把 modules 加入搜索路径
import my_custom_module

注意：路径是相对于当前工作目录的。如果不确定当前目录，可以先用 import os; print(os.getcwd()) 确认。

场景二：跨目录项目结构

scripts/
  main.py
modules/
  __init__.py
  utils.py
  helpers.py

在 main.py 里导入 utils.py：

import sys, os
# 定位到项目根目录
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from modules import utils

这是通用写法，能适应不同的运行目录。

场景三：Package 结构

如果目录里有 __init__.py 文件，Python 会把它识别为一个包。__init__.py 可以为空，也可以在里面写包级初始化逻辑。让 modules/ 成为一个包的方式是：

• 在 modules/ 下创建空的 __init__.py

然后就可以用 from modules.utils import some_function 的方式导入。

查看和修改 sys.path

在 REPL 中随时可以查看和修改：

>>> import sys
>>> sys.path.append("/path/to/my/libs")  # 追加一个搜索路径
>>> sys.path.insert(0, "/better/path")   # 插到最前面（优先搜索）

sys.path 的修改只在当前会话生效，下次打开 QPython 需要重新加。如果希望永久生效，可以在 QPython 的启动配置文件（如果存在的话）里写好。

虚拟环境

早期 QPython 版本不支持虚拟环境（venv 或 virtualenv）。4.0 版本之后的 QPython 3 应该可以运行 python -m venv，但由于手机算力有限，虚拟环境的实际意义不大。

移动端的推荐做法是：

• 在 QPYPI 里管理包（见 PIP 包管理）
• 对项目隔离有强需求时，用不同目录存放各自的 requirements.txt 记录依赖

小结

QPython 的模块导入机制和 PC 上的 Python 完全一致，核心是理解 sys.path 是怎么工作的。日常开发中，当前目录导入最简单；跨目录项目记得在脚本开头用 sys.path.insert 把模块目录加入搜索路径。不需要虚拟环境——手机上一个 QPYPI 足够了。

接下来进入 QEditor 编辑器部分，这是移动端写 Python 的核心工具。