4.5 一个前端项目由哪些文件组成
一、本节你会做出什么
你会打开 2.2 建的那个真实项目，把里面每个文件归入三类：我常改的、偶尔改的、永远别手动动的。
📷 效果位：项目目录树，三种颜色标注的文件分类
为什么这一节重要：第一次打开 AI 生成的项目，看到二十几个文件和文件夹，是很多人放弃的瞬间。 其实绝大多数文件你一辈子都不用打开。这一节就是帮你划清这条线——知道该看哪三个文件，剩下的全部无视。
二、开始前你需要
三、跟着做
第 1 步：先用眼睛看一遍
cd ~/Documents/ai-course/hello-node # 换成你的路径ls你会看到大概这些（版本不同会略有差异）：
hello-node/├── app/ ← 👈 你的页面都在这里│ ├── page.tsx ← 👈 首页│ ├── layout.tsx ← 👈 所有页面的外壳│ └── globals.css ← 全局样式├── public/ ← 👈 图片等静态文件├── node_modules/ ← ⛔ 几百个依赖包，永远别碰├── package.json ← 👈 项目的"身份证 + 零件清单"├── pnpm-lock.yaml ← ⛔ 自动生成，别手改├── next.config.ts ← ⚙️ 框架配置├── tsconfig.json ← ⚙️ TypeScript 配置├── .gitignore ← ⚙️ Git 忽略清单（2.3 讲过）└── README.md ← 项目说明用更好看的方式再看一次（跳过 node_modules，否则会刷屏几万行）：
ls -a # 包括隐藏文件ls app # 看 app 里有什么📷 截图位 1：终端里
ls -a的输出
第 2 步：三个你真正要打开的文件
20 多个文件里，日常只有三个值得你关心。
① app/page.tsx —— 首页
这是你改得最多的文件。 打开它看看（用编辑器，或 cat app/page.tsx）。
你会看到 4.2 学的 HTML 标签（<div> <h1> <main>）混在 JS 里，带着 4.3 学的 Tailwind class。
这种“HTML 长在 JS 里”的写法叫 JSX，4.6 会讲。现在你只要知道：想改首页内容，就是改这个文件。
② app/layout.tsx —— 所有页面共用的外壳
这是最容易被忽略、但很关键的一个文件。
它里面放的是“每一页都有的东西”：
| 放什么 | 为什么放这儿 |
|---|---|
| 网页标题（浏览器标签页上的字） | 每页都要 |
| 顶部导航 Header | 每页都要 |
| 页脚 Footer | 每页都要 |
| 全局字体、主题 | 每页都要 |
🔑 一条实用判断： 只在某一页出现的 → 改
page.tsx；每一页都出现的 → 改layout.tsx。新手常犯的错：想改导航栏，却在
page.tsx里翻半天找不到——因为它在 layout 里。
③ package.json —— 身份证 + 零件清单 + 命令表
打开它：
cat package.json重点看两段：
{ "scripts": { "dev": "next dev", ← 本地开发（2.2 跑的 pnpm dev 就是这个） "build": "next build", ← 打包，部署时用 "start": "next start" }, "dependencies": { "next": "...", ← 这个项目用到的"零件" "react": "...", "react-dom": "..." }}| 段落 | 是什么 | 怎么用 |
|---|---|---|
scripts |
命令表 | 里面写了 dev，你就能跑 pnpm dev。不知道项目怎么启动，先看这里 |
dependencies |
项目运行必需的包 | 看一眼有哪些，知道项目用了什么技术 |
devDependencies |
只在开发时用的包 | 一般不用管 |
🔑 3.5 讲过「不要擅自新增依赖包」，
dependencies就是检查这件事的地方。 AI 改完之后git diff显示package.json变了 → 它装了新东西，去问清为什么。
第 3 步：三个文件夹
| 文件夹 | 放什么 | 你的操作 |
|---|---|---|
app/ |
所有页面和路由。这里的目录结构直接决定网址长什么样（4.8 细讲） | 常进 |
public/ |
图片、图标、字体等静态文件。放这里的东西，用 /文件名 就能访问 |
放素材时进 |
node_modules/ |
下载下来的几百个依赖包 | ⛔ 永远不要打开、不要手改 |
关于 public/，一个常见困惑：
文件放在： public/images/panda.jpg代码里写： /images/panda.jpg ← 注意：没有 public⚠️ 路径里不要带
public。这是图片裂掉的头号原因（4.1 定位表里那条「图片 404」）。
关于 node_modules/，重申 2.2 的话：
它动辄几百 MB，是可再生资源。删掉之后 pnpm install 就回来了。永远不要备份它、不要提交它（.gitignore 已经帮你排除了）。
第 4 步：剩下那些配置文件——认识就行，不用懂
| 文件 | 干什么 | 你需要做什么 |
|---|---|---|
next.config.ts |
框架配置（图片域名、重定向等） | AI 让你改时再看 |
tsconfig.json |
TypeScript 配置 | 基本不用动 |
postcss.config.mjs / tailwind 配置 |
样式工具链配置 | 改主题色时可能会碰 |
pnpm-lock.yaml |
锁定每个包的精确版本 | ⛔ 别手改，但要提交到 Git |
.gitignore |
Git 忽略清单（2.3 讲过） | 偶尔加一行 |
README.md |
项目说明 | 建议写，给未来的自己看 |
💡 关于
pnpm-lock.yaml：它看着像垃圾文件，但必须提交到 Git。它保证你、你的队友、部署平台装的是完全相同的版本。少了它，就会出现“我这儿好的，部署就坏”（4.1 定位表最后一行）。
第 5 步：⚠️ .env.local —— 现在还没有，但你必须先认识它
你的 hello-node 里现在没有这个文件。但从第 7 章起，它会出现，而且是全课最危险的一个文件。
它长这样：
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxDATABASE_URL=postgres://...里面装的是密钥。 三条规矩现在就记住：
| 规矩 | 说明 |
|---|---|
| ① 绝不提交到 Git | .gitignore 默认已排除 .env*（2.3 讲过）。但 AI 从零生成的项目要自己确认 |
| ② 改完要重启 | 改了 .env.local 必须重启 pnpm dev，否则不生效。这是个高频困惑点 |
| ③ 泄露了就换钥匙 | 不是删文件，是去平台把 Key 作废重新生成（2.4 讲过，10.1 详讲） |
🔑 现在就做一件事：打开
hello-node/.gitignore，确认里面有.env*这样的行。终端窗口 有输出就是安全的。
第 6 步：文件地图（本节交付物）
把上面的内容压成一张表。存下来，第一次进陌生项目时对照着看。
| 分类 | 文件 / 文件夹 | 说明 |
|---|---|---|
| 🟢 常改 | app/page.tsx |
首页内容 |
| 🟢 常改 | app/*/page.tsx |
其他页面 |
| 🟢 常改 | app/layout.tsx |
导航、页脚、页面标题 |
| 🟢 常改 | components/ |
组件（4.9 会建） |
| 🟢 常改 | public/ |
图片素材 |
| 🟡 偶尔改 | package.json |
看命令和依赖；装包用命令，不手改 |
| 🟡 偶尔改 | app/globals.css |
全局样式 |
| 🟡 偶尔改 | .gitignore |
加忽略项 |
| 🟡 偶尔改 | next.config.ts / tailwind 配置 |
AI 指导时改 |
| 🔴 只看不改 | .env.local |
密钥，手动维护，绝不提交 |
| ⛔ 永远别动 | node_modules/ |
可再生，pnpm install 会重建 |
| ⛔ 永远别动 | pnpm-lock.yaml |
自动生成，但要提交 Git |
| ⛔ 永远别动 | .next/ / dist/ |
构建产物，每次 build 重新生成 |
💡 一条省心的规矩： 🟢 里的文件放心让 AI 改；🟡 和 🔴 的改动，在
git diff里要停下来看一眼；⛔ 的出现在 diff 里，说明.gitignore配错了。
第 7 步：动手——让 AI 给你画一遍
这是一个很实用的习惯动作，以后每进一个陌生项目都可以用：
在项目目录里启动你的 AI 工具（Pi 就 cd 进去敲 pi），说：
先不要改任何文件。请扫一遍这个项目，给我一张目录说明表：每个文件/文件夹一行，说明它是干什么的，以及我作为新手会不会需要改它。按「常改 / 偶尔改 / 别动」给我分三组。然后和你刚才那张表对照。 对得上，说明你已经看懂这个项目的骨架了。
📷 截图位 2：AI 生成的目录说明表
🔑 4.11 节会把这个动作扩展成一套完整方法：拿到一个完全陌生的项目，五分钟说清它在干什么。本节的文件地图是那套方法的第一步。
四、完成的标志是
- 我用
ls/ls -a看过项目根目录和app/里有什么 - 我知道改首页内容是改
app/page.tsx - 我知道改导航栏/页脚要去
app/layout.tsx（“每页都有的东西在 layout 里”） - 我打开过
package.json，知道scripts是命令表、dependencies是零件清单 - 我知道
git diff里package.json变了意味着装了新包，要问清楚 - 我知道图片放
public/，但代码里引用时路径不带public - 我知道
node_modules/是可再生资源，永远不手动碰 - 我知道
pnpm-lock.yaml不能手改，但必须提交 Git - 我确认了
.gitignore里排除了.env* - 我知道改完
.env.local要重启 dev 才生效 - 我存好了第 6 步那张文件地图
- 我让 AI 生成了一遍目录说明，并和自己的理解对照过
五、卡住了看这里
Q：我的项目结构和课程里写的不一样。
正常。版本不同、创建时选项不同，都会有差异。不变的是那条判断逻辑：页面在 app/（或 src/app/、pages/）、清单是 package.json、依赖在 node_modules/。结构对不上就用第 7 步让 AI 给你画一遍——这比记死某个版本的目录结构有用得多。
Q：我看到项目里有 src/ 目录，app/ 在它里面。
这是另一种常见组织方式（创建项目时的一个选项）。src/app/page.tsx 和 app/page.tsx 作用完全一样，只是多包了一层。
Q：.tsx 和 .jsx 有什么区别？.ts 和 .js 呢？
t 代表 TypeScript —— 带类型检查的 JavaScript。x 代表里面能写 JSX（HTML 式的标签）。
| 后缀 | 是什么 |
|---|---|
.js |
普通 JavaScript |
.ts |
TypeScript |
.jsx |
能写标签的 JS |
.tsx |
能写标签的 TypeScript（本课项目用这个） |
你不需要学 TypeScript。 它的价值是让 AI 写出错误更少的代码，对你来说只是“文件后缀不一样”。
Q：node_modules 占了 500MB，能删吗？
能。删完在项目目录 pnpm install 就回来了（2.2 讲过）。长期不用的旧项目，删掉它能省不少空间。
Q：我不小心改了 pnpm-lock.yaml / 删了 node_modules 里的东西，项目启动不了了。
rm -rf node_modules 然后 pnpm install 重装。lock 文件被改坏了的话，用 2.3 的后悔药：git restore pnpm-lock.yaml。
Q：这些文件我要全记住吗？
不用。只要记住三个文件（page.tsx / layout.tsx / package.json）和两条规矩（图片放 public 但路径不带 public、每页都有的东西在 layout），其余查表。
六、本节提示词
① 项目导览（进任何陌生项目的第一句话，4.11 会升级这条）：
先不要修改任何文件。
请扫一遍当前项目，给我一张目录说明表（markdown 表格）：| 文件/文件夹 | 作用 | 我作为新手会改它吗 |
要求：1. 跳过 node_modules 和构建产物，不要列里面的东西；2. 按「常改 / 偶尔改 / 别动」分三组；3. 特别指出：改首页内容该动哪个文件、改导航栏该动哪个文件；4. 告诉我这个项目怎么启动（从 package.json 的 scripts 里读，不要猜）；5. 如果有 .env 相关文件，提醒我注意什么。
用中文，说人话。② 安全体检（文件层面）：
请检查当前项目的文件配置是否安全：
1. `.gitignore` 里有没有排除 `node_modules`、构建产物、以及**所有 `.env` 系列文件**？2. 有没有任何文件里**明文写着密钥或密码**？（搜一下 api_key、secret、password、token 这类字样）3. 有没有本该被忽略、却已经被 Git 跟踪的文件？4. `public/` 目录里有没有不该公开的东西？（放在 public 的文件任何人都能通过网址访问到）
逐条给结果，有问题的指出具体文件和行号，并告诉我怎么修。③ 这个文件是干什么的（遇到不认识的文件时）：
我的项目里有个文件叫 【文件名】，我不知道它是干什么的。内容是：【粘贴内容，太长就贴前 30 行】
请告诉我：1. 它是干什么的，是谁生成的（我手写的？工具自动生成的？）；2. 我需要改它吗？什么情况下会需要改？3. 它应该提交到 Git 吗？4. 如果我把它删了会发生什么？能恢复吗？上一节 ← 4.4 JavaScript 基础 下一节 → 4.6 为什么需要前端框架：React 在替你做什么