使用python-gitlab操作项目子目录文件时遇404错误，请求排查

针对子目录文件get/create返回404、但repository_tree能正常查到文件的问题，结合GitLab 13.12.12版本特性，提供以下解决方案：

1. 手动编码路径（修复旧版本API编码缺陷） #

GitLab 13.x部分版本存在路径编码处理bug，斜杠分隔的子目录路径在python-gitlab默认处理下无法被API正确识别。可手动对路径做URL编码后传入：

import urllib.parse
import gitlab

gl = gitlab.Gitlab('你的GitLab地址', private_token='你的私有令牌')
project = gl.projects.get('你的项目ID')

# 获取文件时使用编码路径
encoded_path = urllib.parse.quote('test_dir/test_file_created_manually', safe='')
file = project.files.get(file_path=encoded_path, ref='main')

# 创建文件时同样使用编码路径
project.files.create({
    'file_path': encoded_path,
    'branch': 'main',
    'content': '测试内容',
    'commit_message': '在子目录添加文件'
})

2. 提前初始化子目录（旧版本不支持自动创建嵌套目录） #

GitLab 13.12.12的Files API不支持自动创建不存在的嵌套子目录，必须先确保父目录存在。可通过检查目录是否存在，不存在则创建.gitkeep文件初始化目录：

import gitlab

gl = gitlab.Gitlab('你的GitLab地址', private_token='你的私有令牌')
project = gl.projects.get('你的项目ID')
target_dir = 'test_dir'
target_file = f'{target_dir}/test_file_created_manually'

# 检查父目录是否存在
try:
    project.repository_tree(path=target_dir, ref='main')
except gitlab.exceptions.GitlabGetError as e:
    if e.response_code == 404:
        # 创建.gitkeep文件初始化目录
        project.files.create({
            'file_path': f'{target_dir}/.gitkeep',
            'branch': 'main',
            'content': '',
            'commit_message': '初始化子目录'
        })

# 现在创建目标文件
project.files.create({
    'file_path': target_file,
    'branch': 'main',
    'content': '测试内容',
    'commit_message': '在已存在的子目录添加文件'
})

3. 升级适配版本的python-gitlab库 #

旧版本的python-gitlab可能对GitLab 13.x的API兼容性不足，建议升级到适配13.x的最新稳定版（2.10.x系列是最后支持13.x的版本）：

pip install --upgrade python-gitlab==2.10.1

4. 直接调用GitLab REST API绕过封装 #

如果上述方法无效，可直接构造API请求，避免python-gitlab的路径处理问题：

import requests
import urllib.parse

gitlab_url = '你的GitLab地址'
project_id = '你的项目ID'
token = '你的私有令牌'
target_path = 'test_dir/test_file_created_manually'
encoded_path = urllib.parse.quote(target_path, safe='')

# 获取文件
get_url = f"{gitlab_url}/api/v4/projects/{project_id}/files/{encoded_path}?ref=main"
headers = {'PRIVATE-TOKEN': token}
response = requests.get(get_url, headers=headers)
if response.status_code == 200:
    file_data = response.json()
    print(file_data)

# 创建文件
create_url = f"{gitlab_url}/api/v4/projects/{project_id}/files/{encoded_path}"
payload = {
    'branch': 'main',
    'content': '测试内容',
    'commit_message': '通过直接API调用添加文件'
}
response = requests.post(create_url, headers=headers, json=payload)
print(response.status_code, response.json())

内容的提问来源于stack exchange，提问作者Aleksey S.