ArcPro 3.2+中.atbx工具箱本地模块相对导入问题求助

问题普遍性确认 #

是的，大量ArcGIS Pro用户在升级到3.2及以上版本后遇到了这个路径问题。Esri在3.2版本重构了脚本工具的执行沙盒机制，将工具脚本的执行路径从原有的xxx.atbx#xxx.py虚拟路径，改为嵌套在xxx.atbx/xxx.tool/tool.script.execute.py的临时目录下，直接导致了相对路径引用和模块导入的基准目录错位。

目录结构合理性判断 #

你当前的根目录结构完全合理：

• 根目录仅保留工具箱，清晰区分核心工具入口和业务代码
• 拆分my_tools（脚本工具实现）和mylib（通用函数库）两个子文件夹，符合模块化开发规范
• 这种结构适配共享服务器和GitHub的版本控制，无需调整

替代临时方案的优雅解决办法 #

1. 动态定位根目录并临时导入（无全局路径污染） #

避免直接修改全局sys.path并长期保留，而是临时添加根目录，导入完成后移除，减少会话污染风险：

import os
import sys

def get_project_root():
    current_file = __file__
    # 适配3.2+和旧版本的__file__格式
    if ".atbx/" in current_file or ".atbx\\" in current_file:
        root_dir = os.path.dirname(current_file.split(".atbx")[0])
    else:
        root_dir = os.path.dirname(current_file.split(".atbx#")[0])
    return root_dir

# 临时添加根目录到路径
root_dir = get_project_root()
sys.path.append(root_dir)
try:
    from mylib import my_function
finally:
    # 用完立即移除，避免影响其他工具
    if root_dir in sys.path:
        sys.path.remove(root_dir)

2. 利用ArcPy内置属性获取工具箱路径（更可靠） #

直接通过ArcPy的工具环境属性获取工具箱的物理路径，完全不受__file__变化影响：

import arcpy
import os
import sys

# 获取当前工具所在工具箱的绝对路径
toolbox_path = arcpy.env.packageWorkspace
if not toolbox_path:
    #  fallback：从当前项目中获取默认工具箱
    proj = arcpy.mp.ArcGISProject("CURRENT")
    toolbox_path = proj.defaultToolbox

root_dir = os.path.dirname(toolbox_path)
sys.path.append(root_dir)
try:
    from mylib import my_function
finally:
    if root_dir in sys.path:
        sys.path.remove(root_dir)

如果工具不在项目默认工具箱中，可以通过arcpy.GetParameterInfo()或工具的__toolbox__属性（若已定义）精准获取工具箱路径。

3. 将mylib转为可导入包（规范结构） #

在mylib文件夹下添加空的__init__.py文件，将其标记为Python包，结合上面的根目录定位，即可实现更规范的模块导入，同时保持无需安装的特性。

额外建议 #

• 坚持当前的嵌入式库结构，避免让用户单独安装库，能有效减少版本不一致和更新维护成本
• 可以在项目根目录添加README.md，说明工具的使用方式和目录结构，便于团队成员理解

内容的提问来源于stack exchange，提问作者user205308