企业官网建设流程全解析

1. 接手老项目时，为什么我选择先让AI帮我“读”一遍

接手一个三五年甚至更久远的项目，最头疼的往往不是写新功能，而是搞清楚这堆代码到底用了什么、怎么组织的、哪些地方碰不得。我最近就遇到一个典型场景：一个前后端分离的后台管理系统，代码仓库里躺着几十个目录，package.json里依赖上百个，README 只有三行字，原作者早已离职。这种情况下，如果一上来就逐文件翻，没个两三天根本摸不清脉络。

我的做法是：把项目结构、关键配置文件、入口文件丢给 Claude，让它先帮我做一轮技术栈分析。这不是偷懒，而是把 AI 当作一个“不会疲倦的初级分析师”，先产出一份可读的技术栈清单和依赖关系草图，我再基于这份草图去验证、修正、深挖。整个过程我称之为“只管去写”的第二天——第一天是搭环境跑起来，第二天就是搞清楚它到底是个什么东西。

这篇文章适合两类人看：一是刚接手遗留项目、面对陌生代码库不知从何下手的开发者；二是想用 AI 辅助代码理解、但不知道怎么问才有效的朋友。我会把整个分析流程拆开，从准备材料、设计提问、验证结果到避坑经验，全部讲清楚。你不需要有 AI 使用经验，跟着做就能复现。

2. 分析前的准备工作：给AI喂什么、怎么喂

2.1 先搞清楚哪些文件值得喂给AI

老项目最怕的是“信息过载”。一个中型项目动辄几千个文件，全丢给 AI 既不现实也没必要。我的筛选原则是：只喂“骨架文件”和“配置声明文件”。具体来说，下面这几类文件优先级最高：

• 根目录及一级子目录的配置文件：package.json、pom.xml、build.gradle、requirements.txt、go.mod、composer.json等，这些直接声明了依赖和构建方式。
• 构建与打包配置：webpack.config.js、vite.config.ts、rollup.config.js、tsconfig.json、.babelrc等，能看出编译目标和模块规范。
• 入口文件：main.js、index.ts、app.py、Application.java等，能看出启动流程和核心依赖注入方式。
• 目录结构树：用tree -L 3 -I 'node_modules|.git|dist'生成一份三层目录树，让 AI 对项目规模有个整体感知。
• README 和部署脚本：Dockerfile、docker-compose.yml、Makefile、CI 配置等，能看出运行环境和部署方式。

注意：不要喂node_modules、dist、.git这些目录，它们要么是产物要么是版本历史，对技术栈分析没有直接帮助，反而会撑爆上下文。

2.2 生成目录树的实操命令

在项目根目录执行下面这条命令，生成一份干净的目录树：

tree -L 3 -I 'node_modules|.git|dist|build|coverage|.next|.nuxt' -a --dirsfirst > project-structure.txt

参数解释一下：-L 3限制三层深度，避免输出过长；-I排除常见产物目录；-a显示隐藏文件（比如.babelrc、.eslintrc）；--dirsfirst让目录排在文件前面，结构更清晰。生成的文件大概几十到几百行，正好适合贴给 AI。

2.3 把配置文件整理成一份“分析包”

我习惯把关键文件内容合并到一个 Markdown 文件里，每个文件用二级标题隔开，方便 AI 定位。比如：

## package.json （粘贴内容） ## vite.config.ts （粘贴内容） ## src/main.ts （粘贴内容） ## 目录结构 （粘贴 project-structure.txt 内容）

这样做的好处是：AI 在回答时可以直接引用“根据 package.json 第 X 行”，我也能快速对照验证。整理一份分析包大概花 10 分钟，但能省下后面大量来回追问的时间。

3. 向Claude提问的正确姿势：从宽到窄，层层递进

3.1 第一轮提问：要一份技术栈全景图

第一轮不要问太细，先让 AI 给出整体判断。我用的提示词大致是这样的：

你是一名资深架构师。下面是一个老项目的配置文件、入口文件和目录结构。 请帮我分析： 1. 这个项目用到了哪些主要技术栈（前端框架、后端框架、数据库、构建工具、测试框架等），分别列出名称和版本号。 2. 项目的整体架构模式是什么（MVC、前后端分离、微服务、单体等），依据是什么。 3. 有哪些依赖是明显过时或存在兼容风险的，请标注出来。 4. 如果我要在本地跑起来，最可能需要关注哪几个配置项。 请用表格和分点说明，不要泛泛而谈，每个结论都要给出依据（来自哪个文件的哪部分内容）。

这轮提问的关键是要求给出依据。AI 有时候会“脑补”一些不存在的依赖，要求它引用来源能大幅降低幻觉概率。实测下来，Claude 在引用配置文件内容方面比较靠谱，基本能准确指出某个依赖来自package.json的dependencies还是devDependencies。

3.2 第二轮提问：深挖依赖关系和版本冲突

拿到全景图后，第二轮针对可疑点追问。比如第一轮发现项目同时用了moment和dayjs，或者react版本是 16 但某个 UI 库要求 17+，就可以这样问：

根据上一轮分析，我注意到以下疑点： 1. package.json 中同时存在 moment 和 dayjs，请分析可能的原因，以及同时使用会带来什么问题。 2. react 版本为 16.14，但 antd 版本为 5.x，请确认 antd 5 对 react 版本的最低要求，并说明升级路径。 3. 项目中有 webpack 配置和 vite 配置并存，请判断实际使用的是哪一个，依据是什么。 请给出具体的版本兼容性结论和迁移建议。

这轮提问的价值在于：把 AI 从“描述者”变成“诊断者”。它需要交叉比对多个文件的信息，给出有逻辑的判断。我遇到过 AI 判断错的情况，比如它认为webpack.config.js还在用，但实际上package.json的scripts里已经全部换成vite命令了。这种错误正好提醒我：AI 的结论必须验证。

3.3 第三轮提问：生成可执行的验证清单

最后一轮，让 AI 输出一份“人工验证清单”，把它的分析结论转化成可操作的检查项：

请把前面的分析整理成一份验证清单，格式为： - 检查项 | 预期结果 | 验证方法 | 风险等级 例如： - React 版本 | 16.14 | 查看 package.json dependencies | 低 - 构建工具 | Vite 4.x | 运行 npm run build 看输出 | 中

这份清单是我后续手动核对的依据。AI 负责“提出假设”，我负责“验证假设”，分工明确，效率比纯人工翻代码高很多。

4. 实操全流程：一个真实项目的分析记录

4.1 项目背景与初始状态

我接手的这个项目是一个内部使用的数据看板系统，代码仓库约 200 个源文件，package.json里依赖 87 个。README 只写了“npm install && npm run dev”，但实际跑起来报了一堆错。原作者留下的注释里混杂着中英文，部分文件最后修改时间是两年前。

我先按第 2 节的步骤，生成了目录树，收集了package.json、vite.config.ts、tsconfig.json、src/main.ts、src/router/index.ts、src/store/index.ts这几个关键文件，整理成一份约 400 行的分析包。

4.2 第一轮分析结果与初步判断

Claude 返回的技术栈全景如下（我做了精简）：

架构模式判断为“标准 Vue 3 单页应用，前后端分离，前端通过 Axios 调用后端 API”。这个判断和我的预期一致，说明 AI 的基本识别是准确的。

4.3 发现的三个关键问题

第一轮分析中，AI 标注了三个风险点，后来验证都是真实存在的：

问题一：Vite 版本与 Node 版本不匹配。vite.config.ts中使用了defineConfig的某些新特性，但package.json的engines字段没有限制 Node 版本。AI 指出 Vite 4.x 要求 Node 14.18+ 或 16+，而项目部署文档里写的是 Node 12。实测在 Node 12 下pnpm install直接失败。

问题二：Element Plus 按需引入配置缺失。main.ts里是app.use(ElementPlus)全量引入，但vite.config.ts里又装了unplugin-vue-components插件。AI 判断这是“配置冗余”，全量引入会让按需引入插件失效，打包体积偏大。后来我验证发现确实如此，打包产物比预期大了约 40%。

问题三：TypeScript 配置与 Vue 版本不兼容。tsconfig.json中target是es2015，但 Vue 3.2 的某些类型定义需要es2017+。AI 指出这会导致部分类型推断失败，但不影响运行。这个属于“隐性技术债”，不跑类型检查发现不了。

4.4 第二轮追问与验证过程

针对问题一，我追问了具体的 Node 版本要求，AI 给出了 Vite 4.x 的官方要求：Node 14.18+ / 16+。我随后在本地用 nvm 切到 Node 16.20 重新安装，果然顺利通过。

针对问题二，我让 AI 给出了两种修复方案：一是移除全量引入，改用按需自动导入；二是保留全量引入，移除unplugin-vue-components。我选择了方案一，因为项目后续还要加新组件，按需引入更可持续。修改后打包体积从 2.3MB 降到 1.4MB。

针对问题三，AI 建议把target改为es2017，并补充lib字段包含es2017和dom。我照做后，vue-tsc类型检查从 47 个错误降到 3 个（剩下 3 个是业务代码本身的类型问题）。

4.5 最终产出的技术栈文档

整个分析流程走完，我整理了一份约 1500 字的技术栈说明文档，包含：技术栈清单、版本要求、启动步骤、已知问题与修复记录、后续升级建议。这份文档后来成了团队新成员的上手材料，比原来的 README 实用得多。

5. 常见问题与排查技巧实录

5.1 AI 分析结果不准怎么办

AI 分析老项目时，最常见的三类错误是：依赖误判、版本号看错、架构模式判断偏差。我的应对策略是“交叉验证法”：

• 依赖误判：AI 说项目用了某个库，但package.json里没有，可能是它在目录树里看到了相关文件名。这时候直接搜package.json确认。
• 版本号看错：AI 有时会把^1.2.3读成1.2.3，忽略语义化版本的范围含义。重要版本号一定自己再看一眼。
• 架构判断偏差：AI 可能把“有 router 文件”就判断为 SPA，但实际可能是多页应用。结合vite.config.ts的build.rollupOptions.input确认。

我的经验是：AI 的分析结论当“假设”用，不当“事实”用。每个结论花 30 秒验证，整体效率仍然远高于纯人工。

5.2 项目太大，上下文放不下怎么办

超过 500 个文件的项目，一次性喂给 AI 会超出上下文限制。我的做法是分模块分析：先分析根配置和入口，再按src/views、src/components、src/api等目录分批分析。每批分析完，让 AI 输出一份小结，最后把所有小结合并成总览。

另一个技巧是：只喂“声明式”文件，不喂“实现式”文件。比如router/index.ts里定义了所有路由，比逐个看views下的组件文件高效得多。

5.3 老项目依赖装不上时的排查顺序

这是接手老项目最高频的问题。我总结了一个排查顺序表：

这个顺序是我踩了多次坑之后总结的，按这个顺序排查，90% 的安装问题能在 15 分钟内定位。

5.4 让 AI 帮忙写升级方案时的注意事项

老项目升级是大工程，AI 可以帮忙出方案，但有几个坑要注意：

• 不要一次性升级所有依赖。AI 可能会给出“全部升到最新”的建议，这在老项目里是灾难。正确做法是分批升级，每批升完跑一遍测试。
• 要求 AI 给出回滚方案。比如“如果升级后构建失败，如何快速回退”。AI 通常会建议保留旧 lock 文件或打 tag。
• 让 AI 标注破坏性变更。比如 Vue 2 到 Vue 3、Webpack 4 到 5，这些大版本升级有官方迁移指南，让 AI 先列出关键变更点。

6. 用AI分析技术栈的边界与个人体会

6.1 AI 擅长什么、不擅长什么

用了几个月下来，我对 AI 辅助老项目分析的边界有了比较清晰的认识。它擅长的是：识别配置文件中的依赖和版本、根据目录结构推断架构模式、发现明显的配置冲突、生成结构化的文档草稿。它不擅长的是：理解业务逻辑的隐含依赖、判断代码的实际运行路径、评估重构的工作量、处理没有写在配置文件里的“约定俗成”。

举个例子：项目里有一个utils/request.ts封装了 Axios，AI 能看出用了 Axios，但看不出这个封装里藏了一套自定义的 token 刷新逻辑，而这套逻辑又依赖后端某个特定接口。这种“隐性契约”只能靠人读代码或问原团队。

6.2 我的“只管去写”工作流

现在我的标准流程是：第一天搭环境跑起来，第二天用 AI 做技术栈分析并产出文档，第三天开始基于文档做小范围修改验证理解。这个节奏比传统“先读一周代码再动手”快很多，而且产出的文档对团队也有价值。

有一点要强调：AI 分析不能替代实际运行。我见过有人只让 AI 分析完就动手改代码，结果改了半天发现项目根本跑不起来，方向全错。正确的顺序永远是：先跑起来，再分析，再修改。

6.3 一个实用小技巧

最后分享一个我常用的小技巧：让 AI 把分析结果输出成“问答对”格式，比如“Q: 项目用什么构建工具？A: Vite 4.x，依据 vite.config.ts”。这样后续遇到具体问题时，可以直接搜索这份问答文档，比翻长文快得多。我一般会生成 20 到 30 个问答对，覆盖技术栈、启动方式、目录职责、已知问题等维度，基本能应对新成员 80% 的提问。