## 1. 理解%run命令的本质与运行机制 我第一次在Jupyter里用%run跑.py文件时，以为它只是个“快捷执行按钮”，结果调试半天发现变量没传过去，函数调用报错，后来才搞明白：**%run不是简单的脚本调用，而是把整个.py文件的内容像手敲一样“注入”到当前Notebook的命名空间里**。这听起来有点抽象，打个比方——就像你把一个写满代码的纸条，整张贴进当前正在写的笔记本页面里，而不是把它当成一个独立的程序去启动。所以你写的`x = 10`、`def process_data(): ...`、甚至`import pandas as pd`，都会直接出现在当前Notebook的内存中，后续单元格能直接用，不需要再import或重新赋值。 这个机制带来两个关键特性：一是**无隔离性**，脚本里的全局变量会污染当前环境；二是**有上下文继承性**，你在前面单元格定义的变量，也能被.py脚本读取（只要执行顺序对）。我试过在一个Notebook单元格里先写`config = {"mode": "debug"}`，然后用`%run loader.py`，而loader.py里直接写了`print(config["mode"])`——它真能打印出debug。这种“无缝融合”在做快速原型验证时特别爽，比如你刚在Notebook里调试好一段数据清洗逻辑，想把它固化成一个可复用的模块，就直接挪到loader.py里，用%run一跑，立马验证效果，不用反复复制粘贴。 但这也埋了坑。最典型的是重复定义冲突：比如你的notebook里已经`import numpy as np`，而py文件里又写了同样的语句，虽然通常不报错，但万一py文件里用了`np = "fake"`这种覆盖操作，后面所有单元格的np就变字符串了。我踩过一次，花了二十分钟才定位到是某个%run脚本悄悄改了别名。所以实测下来，**%run适合做“功能验证”和“流程串联”，不适合做“模块化封装”**——后者得用import，前者才是%run的主场。 ## 2. 路径处理的四种实战方案 路径问题绝对是新手卡住最多的地方。你敲`%run utils.py`，结果弹出`FileNotFoundError: File 'utils.py' not found`，第一反应肯定是“文件明明就在左边文件浏览器里！”——其实Jupyter找文件，看的不是你眼睛看到的位置，而是**当前kernel启动时的工作目录**。这个目录不一定等于Notebook文件所在目录，尤其当你从终端用`jupyter notebook /path/to/project/`启动，或者用VS Code插件打开时，工作目录可能差着好几层。 我总结出四套亲测有效的路径方案，按推荐度排序： 第一是**相对路径+`.`显式声明**。比如你的Notebook在`/project/notebooks/explore.ipynb`，而py文件在`/project/src/data_loader.py`，那就写`%run ../src/data_loader.py`。注意开头的`../`不能省，哪怕文件就在同级目录，也建议写成`%run ./utils.py`——加个`./`能强制Jupyter从当前目录找，避免歧义。我习惯在每个项目根目录放一个`README.md`，然后所有Notebook都从根目录启动，这样路径全是`./src/xxx.py`或`./notebooks/yyy.py`，一眼看清层级。 第二是**用`os.getcwd()`动态确认位置**。在第一个单元格里加两行： ```python import os print("当前工作目录：", os.getcwd()) ``` 运行后立刻知道Jupyter站在哪儿。如果发现不对，可以用`%cd /correct/path`切换，比如`%cd ~/my_project`。这个命令会永久改变当前kernel的工作目录，后面所有%run都基于新路径。 第三是**绝对路径保稳**。开发机上路径固定的话，直接写全路径最省心：`%run /Users/yourname/projects/ml/src/preprocess.py`。虽然看着长，但复制粘贴一次，后续不用动。我做客户交付时，所有Notebook都用绝对路径，确保换台电脑打开也不崩。 第四是**用`pathlib`构造跨平台路径**（适合复杂项目）： ```python from pathlib import Path script_path = Path(__file__).parent.parent / "src" / "model.py" %run {script_path} ``` 注意这里用了`{script_path}`的f-string格式，Jupyter会自动转成字符串路径。这个方案在Windows和macOS都能跑，而且路径拼接不会因为斜杠方向错乱。 > 提示：用`%pwd`命令能快速查看当前工作目录，比写代码更轻量；用`%ls`能列出当前目录文件，确认py文件是否存在——这两个魔法命令是路径排查的黄金组合。 ## 3. 参数传递与交互控制技巧 %run默认是“静默执行”，脚本里`print()`会输出，但`sys.argv`永远只有`['file.py']`，没法传参。很多人因此放弃%run，转去折腾命令行子进程，其实大可不必——有三个原生技巧能搞定。 第一个是**环境变量法**，最通用。在Notebook里先设好变量： ```python import os os.environ["DATA_PATH"] = "/data/raw/train.csv" os.environ["MODEL_VERSION"] = "v2.1" ``` 然后在your_script.py里读取： ```python import os data_file = os.environ.get("DATA_PATH", "default.csv") print(f"加载数据：{data_file}") ``` 我用这招管理不同环境的配置，开发时设`os.environ["ENV"] = "dev"`，生产Notebook里改成`"prod"`，脚本自动适配，不用改一行代码。 第二个是**全局变量注入法**，适合简单参数。在Notebook里定义变量，再用`%run -i`（i代表interactive）： ```python batch_size = 32 learning_rate = 0.001 %run -i train.py ``` train.py里就能直接用`batch_size`和`learning_rate`，就像它们是在当前Notebook里定义的一样。注意`-i`必须紧挨`%run`，中间不能有空格。这个技巧我常用于超参快速迭代——改几个数字，重跑%run，不用进py文件。 第三个是**重定向输入模拟用户交互**。有些脚本用`input()`等用户输入，%run时会卡住。解决方案是提前准备输入内容，用`%run -i -e`（e代表execute）配合`sys.stdin`重定向： ```python import sys from io import StringIO sys.stdin = StringIO("y\n100\n") # 模拟用户输入'y'回车，'100'回车 %run -i setup.py ``` setup.py里的`choice = input("继续？(y/n): ")`就会自动拿到"y"，`epochs = int(input("训练轮数："))`拿到100。这个在自动化测试脚本行为时特别管用。 > 注意：`%run -i`会把脚本里的变量全部导入当前命名空间，可能导致命名冲突；`%run -i -e`则只执行不导入，更干净。选哪个取决于你是否需要复用脚本里定义的函数。 ## 4. 错误调试与执行状态管理 %run执行失败时，默认只显示最后一行错误，比如`NameError: name 'df' is not defined`，但你根本不知道这行代码在py文件第几行。这时候得开调试模式。最有效的是`%run -d`（debug），它会启动pdb调试器： ```python %run -d analyze.py ``` 报错后自动停在出错行，你可以用`p df`（print变量）、`l`（list代码）、`n`（next行）一步步查。我调试过一个数据读取脚本，发现是编码问题，`-d`模式下直接`p line`看到乱码字符串，秒定位。 另一个高频问题是**多次%run导致重复执行**。比如你写了`model = MyModel()`在py文件里，第一次%run创建了model实例，第二次%run又创建一个，内存里就有两个，还可能互相干扰。解决方案有两个：一是用`%run -t`（time）加时间戳标记，虽然不解决本质问题，但能提醒你“这是第几次跑”；二是更彻底的——**每次%run前清空相关变量**： ```python # 手动删除可能冲突的变量 del model, df, results %run train.py ``` 或者用`%reset_selective -f`精准清理： ```python %reset_selective -f "^model|^df" # 删除所有以model或df开头的变量 %run train.py ``` 执行状态可视化也很实用。我习惯在关键脚本开头加状态打印： ```python # 在train.py第一行 print("[START] 开始训练模型，时间：", __import__('datetime').datetime.now().strftime("%H:%M:%S")) # 结尾加 print("[END] 训练完成，耗时：", __import__('time').time() - start_time) ``` 这样每次%run都能看到清晰的起止标记，配合Notebook的输出折叠，一眼抓住执行段落。 最后强调一个隐形陷阱：**%run不会触发Python的`if __name__ == "__main__":`分支**。如果你的py文件写了这个保护块，里面的内容%run时根本不会执行！因为%run是把代码当模块导入，`__name__`变成`'__main__'`的父级模块名。解决方案很简单——要么删掉这个判断（反正%run就是为直接执行设计的），要么把主逻辑抽成函数，在脚本末尾显式调用： ```python def main(): print("主流程开始") # 所有代码放这里 if __name__ == "__main__": main() else: main() # %run时也会执行 ``` 我在实际项目中，所有供%run调用的脚本都采用这种写法，既兼容命令行直接运行，又适配Notebook场景，一条命令，两处可用。