chanjs 2.7.2 → 2.7.4

package/{helper → utils}/file.js

@@ -17,6 +17,34 @@ export function dirname(importMetaUrl) {
   return path.dirname(url.pathname);
 }
 
+/**
+ * 检查路径是否包含目录穿越字符或绝对路径
+ * @private
+ * @param {string} inputPath - 待检查的路径
+ * @returns {boolean} 是否安全
+ */
+function _isPathSafe(inputPath) {
+  if (!inputPath || typeof inputPath !== 'string') return false;
+  // 拒绝绝对路径（/etc/passwd）和 Windows 盘符（C:\）
+  if (path.isAbsolute(inputPath) && !inputPath.startsWith(process.cwd())) return false;
+  // 拒绝目录穿越
+  const normalized = path.normalize(inputPath);
+  if (normalized.includes('..')) return false;
+  return true;
+}
+
+/**
+ * 校验 fullPath 是否落在 process.cwd() 内
+ * 用 path.relative 避免 startsWith 前缀绕过（如 /project-evil 匹配 /project）
+ * @private
+ * @param {string} fullPath - 已解析的绝对路径
+ * @returns {boolean} 是否在 cwd 内
+ */
+function _isWithinCwd(fullPath) {
+  const rel = path.relative(process.cwd(), fullPath);
+  return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
 /**
  * 删除图片文件
  * @param {string} filePath - 相对于项目根目录的文件路径
@@ -24,7 +52,11 @@ export function dirname(importMetaUrl) {
  * @description
  * 删除指定路径的图片文件
  * 路径是相对于项目根目录（process.cwd()）的
- * 如果文件不存在，不会抛出错误，直接返回 false
+ *
+ * 安全改进：
+ * - 增加防御性路径校验，拒绝绝对路径和目录穿越
+ * - 解析后最终路径必须落在 process.cwd() 内，否则拒绝
+ * - 业务层即使忘做校验也不会被利用删除任意文件
  * @example
  * const deleted = delImg('/uploads/avatar/123.jpg');
  * if (deleted) {
@@ -32,7 +64,16 @@ export function dirname(importMetaUrl) {
  * }
  */
 export function delImg(filePath) {
-  const fullPath = path.join(process.cwd(), filePath);
+  if (!_isPathSafe(filePath)) {
+    console.error('[delImg] 拒绝不安全路径:', filePath);
+    return false;
+  }
+  const fullPath = path.resolve(process.cwd(), filePath);
+  // 二次校验：解析后必须仍在 cwd 内（用 relative 避免 startsWith 前缀绕过）
+  if (!_isWithinCwd(fullPath)) {
+    console.error('[delImg] 路径越界:', filePath);
+    return false;
+  }
   if (fs.existsSync(fullPath)) {
     fs.unlinkSync(fullPath);
     return true;
@@ -52,6 +93,11 @@ export function delImg(filePath) {
  * // 返回: [{ name: 'file.html', path: '/path/to/directory/file.html', type: 'file' }, ...]
  */
 export function getFileTree(dirPath, recursive = true, basePath = null) {
+  // 路径安全校验：拒绝不安全路径直接返回空数组
+  if (!_isPathSafe(dirPath)) {
+    console.error('[getFileTree] 拒绝不安全路径:', dirPath);
+    return [];
+  }
   if (!fs.existsSync(dirPath)) {
     return [];
   }
@@ -61,29 +107,36 @@ export function getFileTree(dirPath, recursive = true, basePath = null) {
     return [];
   }
 
+  // 二次校验：解析后必须仍在 cwd 内
+  const fullPath = path.resolve(process.cwd(), dirPath);
+  if (!_isWithinCwd(fullPath)) {
+    console.error('[getFileTree] 路径越界:', dirPath);
+    return [];
+  }
+
   const items = [];
   const files = fs.readdirSync(dirPath);
   
   const base = basePath || process.cwd();
 
   for (const file of files) {
-    const fullPath = path.join(dirPath, file);
-    const fileStats = fs.statSync(fullPath);
+    const filePath = path.join(dirPath, file);
+    const fileStats = fs.statSync(filePath);
 
     if (fileStats.isDirectory() && recursive) {
-      const children = getFileTree(fullPath, recursive, basePath);
+      const children = getFileTree(filePath, recursive, basePath);
       items.push({
         name: file,
-        path: fullPath,
+        path: filePath,
         type: 'directory',
         children: children
       });
     } else if (fileStats.isFile()) {
-      const relativePath = path.relative(base, fullPath).replace(/\\/g, '/');
+      const relativePath = path.relative(base, filePath).replace(/\\/g, '/');
       items.push({
         name: file,
-        path: fullPath,
-        relativePath: relativePath.startsWith('public') ? '/' + relativePath.replace(/^\//, '') : fullPath,
+        path: filePath,
+        relativePath: relativePath.startsWith('public') ? '/' + relativePath.replace(/^\//, '') : filePath,
         type: 'file',
         size: fileStats.size
       });
@@ -99,20 +152,33 @@ export function getFileTree(dirPath, recursive = true, basePath = null) {
  * @returns {string} 文件内容
  * @description
  * 读取指定文件的内容
+ *
+ * 安全改进：
+ * - 增加防御性路径校验，拒绝绝对路径和目录穿越
+ * - 解析后最终路径必须落在 process.cwd() 内，否则拒绝
+ * - 与 saveFileContent 保持一致的安全策略
  * @example
  * const content = readFileContent('/path/to/file.html');
  */
 export function readFileContent(filePath) {
-  if (!fs.existsSync(filePath)) {
+  if (!_isPathSafe(filePath)) {
+    throw new Error(`[readFileContent] 拒绝不安全路径: ${filePath}`);
+  }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  // 二次校验：解析后必须仍在 cwd 内（用 relative 避免 startsWith 前缀绕过）
+  if (!_isWithinCwd(fullPath)) {
+    throw new Error(`[readFileContent] 路径越界: ${filePath}`);
+  }
+  if (!fs.existsSync(fullPath)) {
     throw new Error('文件不存在');
   }
 
-  const stats = fs.statSync(filePath);
+  const stats = fs.statSync(fullPath);
   if (!stats.isFile()) {
     throw new Error('路径不是文件');
   }
 
-  return fs.readFileSync(filePath, 'utf-8');
+  return fs.readFileSync(fullPath, 'utf-8');
 }
 
 /**
@@ -122,17 +188,31 @@ export function readFileContent(filePath) {
  * @returns {void}
  * @description
  * 将内容保存到指定文件，如果目录不存在会自动创建
+ *
+ * 安全改进：
+ * - 增加防御性路径校验，拒绝绝对路径和目录穿越
+ * - 解析后最终路径必须落在 process.cwd() 内，否则拒绝
+ * - 业务层即使忘做校验也不会被写入任意路径
  * @example
  * saveFileContent('/path/to/file.html', '<html>...</html>');
  */
 export function saveFileContent(filePath, content) {
-  const dirPath = path.dirname(filePath);
-  
+  if (!_isPathSafe(filePath)) {
+    throw new Error(`[saveFileContent] 拒绝不安全路径: ${filePath}`);
+  }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  // 二次校验：解析后必须仍在 cwd 内
+  if (!_isWithinCwd(fullPath)) {
+    throw new Error(`[saveFileContent] 路径越界: ${filePath}`);
+  }
+
+  const dirPath = path.dirname(fullPath);
+
   if (!fs.existsSync(dirPath)) {
     fs.mkdirSync(dirPath, { recursive: true });
   }
 
-  fs.writeFileSync(filePath, content, 'utf-8');
+  fs.writeFileSync(fullPath, content, 'utf-8');
 }
 
 /**
@@ -168,9 +248,20 @@ export function isPathSafe(targetPath, basePath) {
  * // 返回: ['default', 'test', ...]
  */
 export function getFolders(folderPath) {
+  // 路径安全校验：拒绝不安全路径直接返回空数组
+  if (!_isPathSafe(folderPath)) {
+    console.error('[getFolders] 拒绝不安全路径:', folderPath);
+    return [];
+  }
   if (!fs.existsSync(folderPath)) {
     return [];
   }
+  // 二次校验：解析后必须仍在 cwd 内
+  const fullPath = path.resolve(process.cwd(), folderPath);
+  if (!_isWithinCwd(fullPath)) {
+    console.error('[getFolders] 路径越界:', folderPath);
+    return [];
+  }
 
   const items = fs.readdirSync(folderPath);
   const folders = [];

package/{helper → utils}/filter.js

@@ -25,7 +25,8 @@ export function filterFields(data, fields) {
   return data.map((item) => {
     const filteredItem = {};
     for (const field of fields) {
-      if (item.hasOwnProperty(field)) {
+      // 用原型上的方法调用，避免 item 重写 hasOwnProperty 导致原型污染
+      if (Object.prototype.hasOwnProperty.call(item, field)) {
         filteredItem[field] = item[field];
       }
     }

package/{helper → utils}/html.js

@@ -25,6 +25,7 @@ export const escapeScript = (str) => {
 
 /**
  * HTML 解码
+ * 支持：命名实体（amp/lt/gt/quot/apos/nbsp）+ 十六进制数字实体（&#x...;）+ 十进制数字实体（&#...;）
  */
 export function htmlDecode(str) {
   if (typeof str !== 'string') return '';
@@ -36,5 +37,22 @@ export function htmlDecode(str) {
     ''': "'",
     ' ': ' ',
   };
-  return str.replace(/&(amp|lt|gt|quot|apos|nbsp);/g, m => entities[m]);
+  return str
+    .replace(/&(amp|lt|gt|quot|apos|nbsp);/g, m => entities[m])
+    // 十六进制数字实体：&#x3C; → <（含 2/3/4/5/6 位 Unicode）
+    .replace(/&#x([0-9a-f]+);/gi, (_, h) => {
+      try {
+        return String.fromCodePoint(parseInt(h, 16));
+      } catch {
+        return '';
+      }
+    })
+    // 十进制数字实体：&#60; → <
+    .replace(/&#(\d+);/g, (_, d) => {
+      try {
+        return String.fromCodePoint(parseInt(d, 10));
+      } catch {
+        return '';
+      }
+    });
 }

package/utils/index.js

@@ -0,0 +1,34 @@
+/**
+ * 通用工具模块 - 时间/文件/HTML/IP/数据解析/树/过滤
+ */
+// 时间处理
+export { formatTime, formatDateFields } from "./time.js";
+
+// 文件操作
+export {
+  dirname,
+  delImg,
+  getFileTree,
+  readFileContent,
+  saveFileContent,
+  isPathSafe,
+  getFolders,
+} from "./file.js";
+
+// HTML 处理
+export { htmlDecode, htmlEncode, escapeScript } from "./html.js";
+
+// IP 获取
+export { getIp } from "./ip.js";
+
+// 网络请求
+export { request } from "./request.js";
+
+// 数据解析
+export { dataParse, arrToObj, parseJsonFields, buildTree } from "./data-parse.js";
+
+// 树形结构
+export { tree, treeById } from "./tree.js";
+
+// 字段过滤
+export { filterFields } from "./filter.js";

package/{helper → utils}/ip.js

@@ -4,24 +4,29 @@
  * @param {string} [req.ip] - Express 解析的 IP（已包含代理头部解析）
  * @param {Object} [req.headers] - 请求头对象
  * @param {string} [req.headers.cf-connecting-ip] - Cloudflare 连接 IP
+ * @param {string} [req.headers.cf-ray] - Cloudflare 请求追踪 ID
  * @returns {string} 客户端 IP 地址，如果无法获取则返回 "0.0.0.0"
  * @description
  * 从 Express 的 req.ip 获取客户端 IP。
- * 
+ *
  * 注意：需要在 App.js 中设置 trust proxy：
  * app.set("trust proxy", true);
- * 
+ *
  * 设置 trust proxy 后，Express 会自动从以下头部解析真实 IP：
  * - X-Forwarded-For（反向代理，如 Nginx）
  * - X-Real-IP
  * - CF-Connecting-IP（Cloudflare CDN）
- * 
+ *
  * 此方法按优先级从以下来源获取 IP 地址：
- * 1. cf-connecting-ip 请求头（Cloudflare CDN，优先级更高）
+ * 1. cf-connecting-ip 请求头（仅当同时存在 cf-ray 时才信任，防止伪造）
  * 2. req.ip（Express 自动解析，已包含代理头部处理）
  * 3. 默认值 "0.0.0.0"
- * 
- * 此方法适用于部署在反向代理（如 Nginx）或 CDN 后端的应用
+ *
+ * 安全改进：
+ * - 仅当同时存在 cf-ray 头时才信任 cf-connecting-ip
+ * - 避免攻击者直接伪造 cf-connecting-ip 头绕过 IP 限流
+ * - Cloudflare CDN 总是会同时下发这两个头
+ *
  * @example
  * app.use((req, res, next) => {
  *   const ip = getIp(req);
@@ -30,34 +35,38 @@
  * });
  */
 export function getIp(req) {
-  // 1. 优先获取 Cloudflare CDN 透传的真实 IP（优先级最高）
   const headers = req.headers || {};
-  let cfIp = headers["cf-connecting-ip"];
-  if (cfIp) {
-    // 处理可能的多 IP 拼接（部分场景下会传多个 IP，取第一个）
-    cfIp = cfIp.split(',').map(ip => ip.trim())[0];
+
+  // 1. 仅在 CF_ENABLED=true 时信任 cf-* 头部
+  // 单凭 cf-ray 头部仍可被伪造，必须显式声明部署在 Cloudflare 后才信任
+  // 否则攻击者可任意伪造 cf-connecting-ip / cf-ray 绕过 IP 限流
+  if (process.env.CF_ENABLED === 'true' && headers["cf-ray"]) {
+    let cfIp = headers["cf-connecting-ip"];
     if (cfIp) {
-      return cfIp;
+      cfIp = cfIp.split(',').map(ip => ip.trim())[0];
+      if (cfIp) {
+        return cfIp;
+      }
     }
   }
 
   // 2. 其次使用 Express 解析的 req.ip（已处理代理头部）
   if (req.ip) {
     let ip = req.ip;
-    
+
     // 处理 IPv6 映射的 IPv4 地址（如 ::ffff:192.168.1.1 → 192.168.1.1）
     if (ip.startsWith('::ffff:')) {
       ip = ip.substring(7);
     }
-    
+
     // 处理本地回环地址（::1 → 127.0.0.1）
     if (ip === '::1') {
       ip = '127.0.0.1';
     }
-    
+
     return ip;
   }
-  
+
   // 3. 无法获取时返回约定的默认值
   return "0.0.0.0";
 }

package/utils/request.js

@@ -0,0 +1,172 @@
+/**
+ * HTTP 请求工具函数
+ * 提供统一的请求发送方法
+ */
+
+/**
+ * 默认请求超时时间（毫秒）
+ * 防止无超时控制的 fetch 挂起导致连接堆积
+ */
+const DEFAULT_TIMEOUT = 10000;
+
+/**
+ * 最大响应体大小（10MB）
+ * 超过此大小直接拒绝，防止远端返回超大响应导致内存爆炸
+ */
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+
+/**
+ * 内网/特殊地址检查（SSRF 防护）
+ * 拒绝请求内网 IP 和非 http/https 协议
+ * @param {string} urlStr - 待检查的 URL
+ * @returns {Promise<boolean>} true 表示不安全（应拒绝）
+ * @private
+ */
+async function _isPrivateUrl(urlStr) {
+  try {
+    const u = new URL(urlStr);
+    // 仅允许 http/https 协议
+    if (!['http:', 'https:'].includes(u.protocol)) return true;
+    const host = u.hostname;
+    if (!host) return true;
+    // 拒绝 localhost 和内网 IP
+    if (host === 'localhost' || /^(127\.|10\.|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\.|169\.254\.|0\.)/.test(host)) {
+      return true;
+    }
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * 发送 HTTP 请求
+ * @async
+ * @param {string} url - 请求 URL
+ * @param {Object} [options={}] - 请求选项
+ * @param {string} [options.method='GET'] - HTTP 方法
+ * @param {Object} [options.headers] - 请求头
+ * @param {Object|string} [options.body] - 请求体
+ * @param {number} [options.timeout=10000] - 请求超时时间（毫秒），0 表示不超时
+ * @param {number} [options.retry=0] - 失败重试次数，默认 0
+ * @param {number} [options.maxResponseBytes=10485760] - 最大响应字节数，默认 10MB
+ * @returns {Promise<Object|null>} 响应数据，失败时返回 null
+ * @description
+ * 发送 HTTP 请求并返回 JSON 格式的响应数据
+ * - 自动将对象类型的 body 转换为 JSON 字符串
+ * - 默认 Content-Type 为 application/json
+ * - 内置 AbortController 超时控制，默认 10 秒
+ * - SSRF 防护：拒绝请求内网/localhost 地址
+ * - 响应大小限制：超过 maxResponseBytes 拒绝
+ * - response.ok 校验：HTTP 状态码非 2xx 时返回 null
+ * - 失败重试：网络错误时按 retry 次数重试
+ * @example
+ * const data = await request('https://api.example.com/users', {
+ *   method: 'POST',
+ *   body: { name: '张三' },
+ *   timeout: 5000,
+ *   retry: 2
+ * });
+ */
+export async function request(url, options = {}) {
+  const {
+    timeout = DEFAULT_TIMEOUT,
+    retry = 0,
+    maxResponseBytes = MAX_RESPONSE_BYTES,
+    ...restOptions
+  } = options;
+
+  // SSRF 防护：拒绝内网/特殊地址
+  if (await _isPrivateUrl(url)) {
+    console.error(`[Request] SSRF 防护：拒绝请求内网/非法地址: ${url}`);
+    return null;
+  }
+
+  const defaultOptions = {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  };
+
+  const finalOptions = { ...defaultOptions, ...restOptions };
+
+  if (finalOptions.body && typeof finalOptions.body !== 'string') {
+    finalOptions.body = JSON.stringify(finalOptions.body);
+  }
+
+  // 重试逻辑
+  let lastError = null;
+  for (let attempt = 0; attempt <= retry; attempt++) {
+    // 超时控制：通过 AbortController 在指定时间后中止请求
+    let controller = null;
+    let timer = null;
+    if (timeout > 0) {
+      controller = new AbortController();
+      finalOptions.signal = controller.signal;
+      timer = setTimeout(() => controller.abort(), timeout);
+    }
+
+    try {
+      const response = await fetch(url, finalOptions);
+
+      // HTTP 状态码校验：非 2xx 视为失败
+      if (!response.ok) {
+        console.error(`[Request] HTTP ${response.status} ${response.statusText}: ${url}`);
+        return null;
+      }
+
+      // 响应大小校验：content-length 超限直接拒绝
+      const contentLength = parseInt(response.headers.get('content-length') || '0', 10);
+      if (contentLength && contentLength > maxResponseBytes) {
+        console.error(`[Request] 响应体过大 (${contentLength} bytes > ${maxResponseBytes}): ${url}`);
+        return null;
+      }
+
+      // 流式读取时累计字节数，超过上限中止
+      const reader = response.body?.getReader();
+      if (reader) {
+        const chunks = [];
+        let totalSize = 0;
+        let done = false;
+        while (!done) {
+          const { done: rDone, value } = await reader.read();
+          done = rDone;
+          if (value) {
+            totalSize += value.length;
+            if (totalSize > maxResponseBytes) {
+              console.error(`[Request] 流式响应体超过上限 (${totalSize} > ${maxResponseBytes}): ${url}`);
+              await reader.cancel?.();
+              return null;
+            }
+            chunks.push(value);
+          }
+        }
+        const buf = Buffer.concat(chunks);
+        try {
+          return JSON.parse(buf.toString('utf8'));
+        } catch (e) {
+          console.error('[Request] JSON 解析失败:', e.message);
+          return null;
+        }
+      }
+
+      // 无 body 流的兜底（理论上极少走到）
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        console.error(`[Request] 请求超时 (${timeout}ms): ${url}`);
+      } else {
+        console.error(`[Request] 请求失败 (attempt ${attempt + 1}/${retry + 1}):`, error.message);
+      }
+      lastError = error;
+      // 仅网络错误重试，超时不重试（避免雪崩）
+      if (error.name === 'AbortError') break;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  return null;
+}

package/{helper → utils}/time.js

@@ -77,7 +77,7 @@ export function formatDateFields(data, fields) {
 
   const result = { ...data };
   
-  const defaultFields = ['createdAt', 'updatedAt', 'created_at', 'updated_at', 'createdAt', 'updatedAt'];
+  const defaultFields = ['createdAt', 'updatedAt', 'created_at', 'updated_at'];
   const targetFields = fields || defaultFields;
   
   for (const field of targetFields) {

package/utils/tree.js

@@ -0,0 +1,121 @@
+/**
+ * 树形结构工具函数
+ * 提供数组转树形结构和路径查找功能
+ */
+
+/**
+ * 默认最大递归深度，防止循环引用导致栈溢出
+ */
+const DEFAULT_MAX_DEPTH = 20;
+
+/**
+ * 将扁平数组转换为树形结构
+ * @param {Array<Object>} arr - 扁平化的数据数组
+ * @param {number} [pid=0] - 父节点 ID，默认为 0
+ * @param {Object} [opts] - 选项
+ * @param {number} [opts.maxDepth=20] - 最大递归深度
+ * @param {Set} [opts._visited] - 已访问节点 id 集合（防循环引用，内部用）
+ * @param {number} [opts._depth=0] - 当前递归深度（内部用）
+ * @returns {Array<Object>} 树形结构数组
+ * @description
+ * 递归构建树形结构，为每个节点添加 level 属性
+ * 如果有子节点，则添加 children 属性
+ *
+ * 安全改进：
+ * - maxDepth 限制递归深度，防止恶意数据导致栈溢出
+ * - _visited 跟踪已访问的 id，遇到循环引用时立即终止
+ * @example
+ * const arr = [
+ *   { id: 1, pid: 0, name: '根节点' },
+ *   { id: 2, pid: 1, name: '子节点' },
+ *   { id: 3, pid: 2, name: '孙节点' }
+ * ];
+ * const tree = tree(arr);
+ * // 返回带有 children 和 level 的树形结构
+ */
+export function tree(arr, pid = 0, opts = {}) {
+  const maxDepth = opts.maxDepth || DEFAULT_MAX_DEPTH;
+  const visited = opts._visited || new Set();
+  let depth = opts._depth || 0;
+
+  // 空数组 / 超过最大深度 / 循环引用检测
+  if (!Array.isArray(arr) || arr.length === 0) return [];
+  if (depth >= maxDepth) {
+    console.warn(`[tree] 已达到最大递归深度 ${maxDepth}，可能存在循环引用`);
+    return [];
+  }
+  if (visited.has(pid)) {
+    console.warn(`[tree] 检测到循环引用，pid=${pid} 已访问过`);
+    return [];
+  }
+  visited.add(pid);
+
+  let result = [];
+  arr.forEach((item) => {
+    if (item.pid === pid) {
+      let children = tree(arr, item.id, { maxDepth, _visited: visited, _depth: depth + 1 });
+      if (children.length) {
+        item.children = children;
+      }
+      item.level = 1;
+      result.push(item);
+    }
+  });
+  return result;
+}
+
+/**
+ * 根据 ID 查找节点路径
+ * @param {number} id - 要查找的节点 ID
+ * @param {Array<Object>} source - 数据源数组
+ * @param {Object} [opts] - 选项
+ * @param {number} [opts.maxDepth=20] - 最大递归深度
+ * @returns {Array<Object>} 从根节点到目标节点的路径数组
+ * @description
+ * 递归查找指定 ID 的节点及其所有父节点
+ * 为每个节点添加 path 属性，包含拼音路径
+ *
+ * 安全改进：
+ * - maxDepth 限制递归深度，防止恶意数据导致栈溢出
+ * - 用 visited 集合检测循环引用
+ * @example
+ * const arr = [
+ *   { id: 1, pid: 0, pinyin: 'root' },
+ *   { id: 2, pid: 1, pinyin: 'child' }
+ * ];
+ * const path = treeById(2, arr);
+ * // 返回包含 root 和 child 节点的数组
+ */
+export function treeById(id, source, opts = {}) {
+  const maxDepth = opts.maxDepth || DEFAULT_MAX_DEPTH;
+  const arr = [];
+  const visited = new Set();
+
+  const findId = (id, source, depth = 0) => {
+    if (depth >= maxDepth) {
+      console.warn(`[treeById] 已达到最大递归深度 ${maxDepth}，可能存在循环引用`);
+      return;
+    }
+    if (visited.has(id)) {
+      console.warn(`[treeById] 检测到循环引用，id=${id} 已访问过`);
+      return;
+    }
+    visited.add(id);
+    for (let i = 0, item; i < source.length; i++) {
+      item = source[i];
+      if (item.id == id) {
+        arr.unshift(item);
+        if (item.pid != 0) {
+          findId(item.pid, source, depth + 1);
+        }
+      }
+    }
+  };
+  findId(id, source);
+  const _path = [];
+  arr.forEach((item) => {
+    _path.push("/" + item.pinyin);
+    item.path = _path.join("");
+  });
+  return arr;
+}