directory_map() 返回空数组主因是传入相对路径，它只接受绝对路径；中文乱码源于 locale 编码不匹配；$depth 非层级限制而是递归开关；返回嵌套数组键名为 basename 而非完整路径，结构难处理。
directory_map() 返回空数组？检查路径是否为相对路径
CodeIgniter 的 directory_map() 默认只接受服务器绝对路径，传入像 "assets/images" 这种相对路径会静默失败，返回空数组。它不是按当前工作目录拼接的，而是直接交给 PHP 的 scandir() 处理，而 scandir() 对相对路径的解析依赖于执行脚本所在位置（比如 CLI 下是入口文件路径，Web 下可能是 index.php 所在目录），极易不一致。
实操建议：
- 始终用
FCPATH或APPPATH等常量拼出绝对路径，例如：directory_map(FCPATH . 'uploads/') - 传入前加一层判断：
if (! is_dir($path)) { log_message('error', "Path not found: $path"); } - Windows 下注意反斜杠问题，统一用正斜杠或
str_replace('\', '/', $path)预处理
中文目录名乱码或跳过？PHP 文件系统编码没对齐
directory_map() 底层调用 scandir()，而该函数在 Linux/macOS 上默认按字节读取目录项，在 Windows 上受当前 ANSI 代码页影响。如果目录含中文但文件系统编码是 UTF-8（现代 Linux/macOS 默认），而 PHP 运行环境 locale 不支持 UTF-8（如某些旧 Docker 镜像设为 C 或 en_US），就会出现跳过、乱码或 Warning: scandir(): failed to open dir。
实操建议：
- 确认 PHP 所在系统 locale：运行
locale命令，确保LANG和LC_ALL包含UTF-8 - Docker 中需在
Dockerfile加：ENV LANG=C.UTF-8 LC_ALL=C.UTF-8 - 避免依赖
directory_map()直接处理含中文路径，可先用glob(FCPATH . 'uploads/*')+basename()替代
递归层级被截断？$depth 参数不是深度限制而是“是否递归”开关
很多人以为 $depth = 2 表示最多遍历两层子目录，实际 directory_map($path, $depth) 的 $depth 是布尔型语义：0 表示不递归（只列一级），非 0（如 1、99、-1）都表示**完全递归**，没有中间档位。官方文档没写清楚，源码里就是 if ($depth !== 0) 判断。
实操建议：
- 需要控制层级时，不能靠
$depth，得自己封装递归逻辑，用iterator_count(new RecursiveIteratorIterator(new RecursiveDirectoryIterator($path)))辅助计数 - 若只是想排除某类子目录（如
.git、node_modules），应在回调中过滤，directory_map()不支持 exclude 参数 - 大目录下慎用无限递归，容易超内存或超时，建议加
set_time_limit(30)和ini_set('memory_limit', '64M')
返回结果结构难处理？数组键名不是文件名而是带斜杠的路径片段
directory_map() 返回的是嵌套关联数组，键名是目录/文件的 basename，但值可能是子数组（目录）或字符串（文件）。关键点在于：**它把路径分段后，用每一段的 basename 当键，而不是完整路径**。比如 uploads/2023/photo.jpg 会变成 ['uploads' => ['2023' => ['photo.jpg' => 'photo.jpg']]] —— 这导致你无法直接知道 photo.jpg 的真实路径，也无法区分同名文件在不同子目录下的冲突。
实操建议：
- 不要直接 foreach 输出，先用
array_keys_recursive()（需自定义）扁平化提取所有文件路径 - 更可靠的做法是绕过
directory_map()，改用 SPL：$it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($path)); foreach ($it as $file) { if ($file->isFile()) echo $file->getRealPath(); } - 若必须用
directory_map()，记得它对隐藏文件（以.开头）默认忽略，要包含需修改源码或提前chmod +r目录
真正麻烦的不是怎么调用这个函数，而是它把路径语义和数据结构耦合得太紧——你拿到的不是“文件列表”，而是一棵被强制按目录树展开的、键名不可靠的数组。很多项目卡在这里，其实是没意识到 CI 这个 Helper 本质是个轻量胶水，不是通用文件扫描器。
