上一篇我列出了 Codex 接手陌生前端项目时需要先确认的 5 个入口项目边界、项目规则、执行入口、应用启动入口和当前业务入口。接下来要解决一个更具体的问题真正打开仓库以后这些入口应该怎样读才能快速建立一张可信的项目地图我在第 008 篇文章里已经给过一张通用项目地图它包含规则、入口、职责、行为与状态、复用与差异、影响与验证六层。那张地图回答的是“一个任务需要掌握哪些信息”。今天这篇不重复列信息项而是往前再走一步第一次面对陌生项目时怎样从最少的一组文件开始得到第一个可以用于定位任务的子图。我把这组阅读对象压缩成三层目录层代码被分成了哪些边界配置层这些边界怎样被解析和执行入口层应用怎样真正启动并连接到业务页面。三层不能分开看。目录给出候选结构配置解释目录含义入口证明哪条路径正在运行。项目地图不是一棵漂亮的目录树下面这种输出很常见src/ ├─ api/ 接口 ├─ components/ 组件 ├─ router/ 路由 ├─ stores/ 状态 ├─ utils/ 工具 └─ views/ 页面它没有错却几乎不能支持真实修改。我仍然不知道api是否是唯一请求入口components是全局组件、业务组件还是两者混合路由是静态声明、模块扫描还是构建生成stores中的状态由谁安装、何时恢复views中哪个页面真的挂在当前应用上别名、环境变量和插件是否改变了实际引用关系。如果项目地图只把目录名翻译成中文它只是导航不是证据。我认可的最小项目地图至少要能回答从项目脚本启动以后配置怎样解析代码入口怎样装配应用用户怎样走到目标页面第一层读目录但只识别边界和异常目录层的任务不是展开所有文件而是识别项目的天然边界。我会分三轮读。第一轮只看仓库顶层先判断是单应用还是工作区应用与公共包怎样分布是否有服务端、移动端、脚本或文档共存在同一仓库是否有旧版、生成产物、缓存和依赖目录需要排除项目规则文件位于哪里。这一轮不急着进入src。假设看到下面的演示结构workspace/ ├─ apps/ │ ├─ console/ │ └─ portal/ ├─ packages/ │ ├─ shared-ui/ │ └─ request/ ├─ scripts/ ├─ docs/ ├─ package.json └─ workspace-config我先得到的不是“有两个应用、两个包”这种描述而是几个需要验证的判断当前任务属于console还是portal两个应用是否真的引用shared-ui和request顶层脚本是否统一调度子应用scripts是否参与生成路由、类型或环境配置哪个目录中的规则对目标应用生效。这些判断要在配置层验证不能只凭名字确认。第二轮进入目标应用顶层目标应用确定后我只看它的第一层结构依赖清单与脚本构建和类型配置环境文件静态资源源码目录测试目录本地开发说明。这一轮重点找“异常信号”应用内部还有第二个package.json存在多个源码根目录有多个构建配置或入口 HTML测试与源码不在同一包环境文件数量很多路由或类型可能由脚本生成同时存在新旧两套路由、状态或请求目录。异常信号不是坏事但它意味着不能套用框架默认结构。第三轮围绕当前任务展开源码进入源码后我不做全量文件清单只展开与启动链和业务入口有关的目录脚本入口和根组件路由与权限状态装配目标页面与直接子组件相关请求与类型可复用实现对应测试。目录层到这里就应该停止。它的产出是边界和候选路径不是最终结论。目录层应该留下什么证据我会把结果整理成下面的格式边界候选位置当前判断仍需验证目标应用具体应用目录当前需求可能属于这里由脚本和路由确认公共组件本地包或源码目录可能影响目标页面由依赖和引用确认请求层应用内或公共包可能存在统一封装由入口和调用确认路由路由目录或生成脚本页面可能动态注册由构建配置和入口确认测试应用内或顶层目录可作为验证入口由脚本作用范围确认这里刻意使用“候选”“可能”和“仍需验证”。目录层能够提出问题但不能替配置和引用关系作证。第二层读配置解释代码为什么这样被找到和运行配置层是项目地图中最容易被跳过、也最容易制造误判的一层。很多人找到main.ts就直接向下读但如果没有先看配置下面这些问题可能都理解错/实际指向哪个目录同一个别名在构建与类型系统中是否一致哪些环境变量会切换接口、路由或功能是否使用插件自动导入组件、路由或 API入口 HTML 加载的是哪个脚本开发和生产构建是否使用不同配置测试环境怎样解析模块哪些文件由工具生成不能直接编辑。我会按四组读取配置第一组依赖与脚本先看包管理、工作区、依赖和脚本确认项目使用的框架与构建工具来自真实依赖而不是目录猜测启动、构建和检查脚本作用于哪个应用脚本是否注入模式、环境或额外参数是否存在生成、预处理和联动脚本。第二组构建配置构建配置主要回答源码根和公开路径别名插件开发代理构建输出多入口或条件配置自动导入和文件扫描。我尤其关注插件因为插件可能改变表面目录与运行代码之间的关系。路由文件没有显式导入页面不代表没有路由组件没有手动导入不代表它来自全局注册某些类型文件出现在源码中也可能是生成产物。第三组类型与代码检查配置类型配置、Lint 和测试配置会说明哪些文件被真正纳入检查路径别名在检查工具中怎样解析是否排除了某些旧目录或生成目录测试环境和源码环境有什么差异项目认为哪些错误必须阻断交付。只运行一条命令不看它覆盖什么很容易得到过度结论。第四组环境配置环境配置要回答当前脚本加载哪个模式哪些变量参与接口地址、路由基础路径、权限或功能开关是否存在本地、测试、预发和生产差异变量在哪里声明和使用哪些敏感值不应复制到文章、日志或任务上下文。读取环境配置的目标是理解条件分支不是输出其中的具体值。配置不能单独下结论要做三组交叉验证构建别名与类型别名交叉验证如果构建工具把指向一个目录类型配置却指向另一个目录说明项目可能存在历史问题或多环境差异。不能只选一个看起来合理的解释。脚本模式与环境文件交叉验证脚本传入的模式应该能对应实际加载的环境文件和代码分支。仅看到多个环境文件不能判断当前任务使用哪一个。插件扫描与真实文件交叉验证配置声明扫描某个目录还要确认该目录中生成或注册了什么以及业务入口是否真正使用它。配置层完成后我会把“目录中的可能”收缩为“配置支持的候选路径”。下一步再用入口和引用关系证明哪条路径实际生效。第三层读入口建立一条能跑通的启动链入口层是最小项目地图的收尾。它不是只找到main.ts而是沿真实加载关系走完下面这条链执行脚本 → 构建入口 → HTML 容器 → 脚本入口 → 应用实例 → 根组件 → 插件与路由 → 目标业务页面不同项目可能省略、合并或替换其中某些节点顺序也应以真实配置为准。第一步从执行脚本反推构建入口我先确认启动命令实际调用哪个工具、加载什么模式、工作目录在哪里。然后在构建配置中找到入口 HTML、脚本入口或多应用选择逻辑。这样可以避免直接打开一个常见文件名却没有证明它属于当前启动路径。第二步从脚本入口看应用装配在入口文件中重点看应用怎样创建根组件是谁路由和状态何时安装权限、国际化、组件库和全局能力怎样注册挂载前是否执行初始化、配置加载或身份恢复是否存在环境条件分支。我不会在这一阶段深入每个插件的实现只记录它是否可能影响当前业务任务。第三步从路由或父级入口找到目标页面目标页面必须通过可证明的路径定位静态路由中的组件引用模块路由的聚合关系文件扫描或生成路由的规则菜单与路由映射父页面对子组件的真实引用。名称搜索可以辅助发现文件但最终要回到引用和运行入口。第四步从页面向下一层跟踪数据和状态最小地图不需要展开所有业务逻辑只记录页面主要输入来自哪里使用哪个状态来源请求经过哪一层关键子组件怎样通信当前任务最可能影响哪些位置用哪些检查或页面路径验证。到这里项目地图就从“目录中可能有这个页面”变成了“这个页面由当前启动路径实际加载并通过这些责任边界完成行为”。一个演示项目三层阅读怎样互相修正下面只用于说明方法不代表真实项目经历。假设目录层看到src/ ├─ main.ts ├─ router/ ├─ pages/ ├─ stores/ └─ services/最初可能得到几个猜测main.ts是入口router声明路由pages存放页面services负责请求。进入配置层后发现构建插件会扫描pages生成路由service别名实际指向一个本地公共包而不是src/services测试配置没有包含浏览器交互测试开发脚本根据模式加载不同接口代理。目录层的两个判断被修正路由不是完全手写页面请求也不一定经过本地services。进入入口层后又发现main.ts在挂载前加载运行时配置生成路由还要经过权限过滤后才安装目标页面通过一个布局组件进入页面真正使用的是公共请求包中的封装。这时最小地图才闭合开发脚本与当前模式 → 构建配置和页面扫描插件 → main.ts 加载运行时配置 → 安装状态与权限过滤后的路由 → 布局组件 → 目标页面 → 公共请求包如果只读目录我会得到一张看起来正确、实际缺少关键条件的地图。我要求每一条地图结论都带证据级别为了防止推断混入事实我会给地图结论标三种状态。已确认有直接配置、代码引用或可运行结果支持。例如目标路由明确引用该页面入口文件实际安装该路由目标脚本能够启动对应应用。待验证当前证据支持一种解释但还缺少运行、调用方或环境确认。例如某个请求封装看起来是统一入口但尚未查完目标功能的所有调用。有冲突目录、配置、规则或稳定实现给出不同答案需要人确认或继续调查。例如构建别名与类型别名不一致两个路由系统同时存在文档与当前脚本不匹配。只有“已确认”内容可以直接进入执行计划。“待验证”应该变成计划的前置检查“有冲突”则应该成为暂停条件。一份可复用的最小项目地图模板# 当前任务最小项目地图 ​ ## 0. 任务坐标 - 目标应用 - 当前任务 - 明确不进入的范围 ​ ## 1. 目录层 ### 仓库边界 - 应用 - 公共包 - 脚本、文档、旧版和生成目录 ​ ### 目标应用边界 - 源码根 - 配置与环境文件 - 测试位置 - 当前业务候选目录 ​ ### 异常信号 - 多入口 - 新旧结构并存 - 生成代码或自动扫描 ​ ## 2. 配置层 ### 依赖与脚本 - 包管理和工作区 - 启动、构建与检查脚本 - 脚本作用范围 ​ ### 构建与解析 - 构建入口 - 别名 - 关键插件 - 环境和代理 - 自动生成或扫描 ​ ### 检查范围 - 类型检查覆盖 - 测试覆盖 - 构建能证明什么 ​ ## 3. 入口层 - 执行脚本 - HTML 或构建入口 - 脚本入口 - 根组件 - 路由和状态装配 - 权限、国际化和全局能力 - 目标业务入口 ​ ## 4. 当前任务链路 - 用户入口 - 页面和组件 - 状态来源 - 请求与数据转换 - 预计修改位置 - 验证出口 ​ ## 5. 证据状态 ### 已确认 - 结论 文件或配置依据 ​ ### 待验证 - 推断 缺少的证据 ​ ### 有冲突 - 冲突内容 下一步处理 ​ ## 6. 是否进入修改计划 - 可以进入 - 仍需先解决这份模板不要求把所有栏目都写得很长。对于局部任务地图可以只覆盖一条启动链和一条业务链对于公共组件或高风险任务再扩大到其他应用和调用方。地图什么时候算够用而不是继续无限阅读陌生项目很容易让人陷入另一个极端总觉得还没读完不敢开始修改。我会用五个问题判断最小地图是否足够能否证明目标页面属于当前启动的应用能否说明项目规则和配置怎样约束当前实现能否沿用户入口找到页面、状态和请求的主要责任边界能否列出预计修改位置和默认不修改范围能否说明完成后运行什么检查、走什么页面路径五个问题都有证据就可以进入执行计划。阅读的目标不是掌握整个仓库而是把当前任务从模糊位置放进一个可修改、可验证的坐标系。如果某个问题无法回答就继续读与它直接相关的文件而不是无差别扩大上下文。三种看起来像地图、其实还不能使用的输出只有目录说明“views放页面api放接口”没有说明当前任务实际使用哪一条路径。只有技术栈清单列出 Vue、TypeScript、构建工具和组件库不等于理解项目怎样装配这些能力。只有文件列表列出十几个“可能需要修改”的文件却没有说明依赖顺序、用户入口和验证出口只会把不确定性推给后续实现。真正可用的地图必须包含关系哪个配置解释哪个目录哪个入口加载哪个页面哪个状态或请求层对当前行为负责。写在最后目录、配置和入口文件并不是三个独立的阅读清单而是三层互相校验的证据目录层发现边界和候选路径配置层解释模块怎样被解析、生成和执行入口层证明当前应用怎样启动并走到目标页面。我让 Codex 建立最小项目地图时不要求它复述整个仓库而是要求它回答一条具体链路当前脚本启动哪个应用配置怎样影响模块与环境入口怎样装配路由和状态用户最终怎样进入当前业务功能。这条链一旦有证据后面的修改计划才不需要建立在目录名称和框架习惯上。下一篇会沿第 2 周 Day 2 继续推进Codex 已经找到正确项目和入口以后怎样识别并遵守现有代码风格哪些内容应该写成明确项目规则哪些只能作为局部参考避免为了“统一”制造无关修改。本系列持续更新。后续会继续把项目规则、调用链、代码差异和验证方式接入这张最小地图逐步完成一次可交付的前端任务闭环。每日好工具推荐在这里推荐一款超好用的图片压缩工具——“图压”在线图片压缩免费压缩 JPG、PNG、WebP - 图压工具。同事安利给我的用过后真的觉得太香了支持批量压缩、调整压缩百分比最关键的是它是离线程序下载到本地就能反复用。我平时做自媒体和写前端时经常用到再也不用去网上找在线压缩工具了。它也带在线压缩功能很方便。