本地联调防火墙用 Python 做 Monorepo 依赖自检在大型项目或全栈开发中Monorepo单仓多包架构越来越常见。为了在本地快速调试不同包之间的交互开发者通常会在package.json里用file:协议声明本地路径依赖比如core: file:../core。但这种做法有个隐患如果引用的本地包没编译或者代码里写了绝对路径上线时可能直接报错。一、本地联调的痛点假设核心库package A被业务工程package B通过本地路径引用。当你在package B启动开发服务器时打包工具会通过软链接读取package A的源码。常见问题有两个编译产物缺失如果package A只改了 TypeScript 源码没执行npm run build生成dist/目录本地测试可能正常因为直接读了源码但线上构建会报错——因为构建系统拉取的是未生成的dist/目录。敏感文件泄露如果package A的package.json没配置好files白名单可能意外把.env密钥或tests/目录打包进去导致安全隐患。核心问题如何在发包前自动检查本地依赖的编译状态和文件白名单二、自检方案静态分析本地依赖我们设计了一个轻量级检查流程graph TD A[启动打包流水线] -- B[解析 package.json 依赖声明] B -- C[筛选 file:/link: 本地依赖] C -- D{检查路径是否存在?} D -- 否 -- E[报错路径失效] D -- 是 -- F{检查入口文件是否存在?} F -- 否 -- G[报错未编译] F -- 是 -- H{检查 files 白名单是否含敏感词?} H -- 含敏感词 -- I[报错泄露风险] H -- 合规 -- J[允许发布]这个流程能拦截两类问题本地依赖未编译dist/目录缺失白名单配置错误包含.env、test/等敏感路径三、Python 实现轻量级审计工具下面是一个用 Python 原生模块实现的检查脚本不依赖第三方库# local_dep_auditor.py import json import os import sys # 禁止包含的敏感关键词 FORBIDDEN {.env, secret, credentials} def log(msg, errorFalse): prefix \033[31m[ERROR]\033[0m if error else \033[36m[Auditor]\033[0m print(f{prefix} {msg}) class DependencyAuditor: def __init__(self, pkg_json_path): self.root os.path.dirname(os.path.abspath(pkg_json_path)) def audit(self): with open(self.root / package.json) as f: pkg json.load(f) errors [] for dep, version in {**pkg.get(dependencies, {}), **pkg.get(devDependencies, {})}.items(): if not version.startswith((file:, link:)): continue dep_path os.path.normpath(os.path.join(self.root, version.split(:)[1])) # 检查路径存在性 if not os.path.exists(dep_path): errors.append(f❌ {dep}: 路径不存在 ({dep_path})) continue # 检查编译产物 dep_pkg_path dep_path / package.json if not os.path.exists(dep_pkg_path): errors.append(f❌ {dep}: 缺少 package.json) continue with open(dep_pkg_path) as f: dep_pkg json.load(f) main_file dep_pkg.get(main, ) if main_file and not os.path.exists(dep_path / main_file): errors.append(f❌ {dep}: 入口文件缺失 ({main_file})请运行 build) # 检查白名单 for pattern in dep_pkg.get(files, []): if any(kw in pattern.lower() for kw in FORBIDDEN): errors.append(f⚠️ {dep}: 白名单含敏感路径 ({pattern})) if errors: log(发现以下问题, errorTrue) for e in errors: print(f {e}) return False log(✅ 所有本地依赖检查通过) return True if __name__ __main__: auditor DependencyAuditor(package.json) sys.exit(0 if auditor.audit() else 1)关键逻辑扫描dependencies和devDependencies中的file:/link:依赖检查对应路径是否存在验证main字段指向的文件是否真实存在即是否已编译检查files白名单是否包含敏感关键词四、工程实践中的取舍file:vsnpm linknpm link会创建全局软链可能导致模块冲突比如重复加载 React。file:协议更明确推荐优先使用。CI/CD 中的路径替换本地file:../lib依赖不能直接部署需在构建流程中替换为正式版本号。可以用replace-in-file等工具在打包前处理package.json。缓存问题本地修改后Vite/Webpack 可能因缓存未刷新。建议在package.json的dev脚本中加入缓存清理scripts: { dev: rimraf .vite_cache vite }五、总结Monorepo 本地联调需要平衡效率和安全性。通过在 CI 前加入这个轻量级检查脚本可以提前发现未编译的依赖防止敏感文件泄露减少线上构建失败的概率工具本身只有 50 行代码但能拦截大部分本地联调中的低级错误。建议集成到precommit或prepublish钩子中强制团队遵守依赖规范。
