AI 与技术通识 · 个人知识站
第 5 课:准备开发环境,让 AI 真正参与建站
用 Next.js、TypeScript、Tailwind CSS、MDX、Git 和 TRAE 建立一套能启动、能被 AI 理解、每次修改都可检查和回退的个人网站项目。
你现在真正要解决的问题
你已经有定位卡、内容地图、承接路径和页面 Brief。此时若把四份文件丢给 AI,说“帮我做个高级网站”,它可能同时创建首页、文章、支付、登录、数据库,还顺手更换框架。页面报错时,你不知道是它改坏了文件、依赖没装完、还是自己不在正确目录;想回到昨天能运行的版本,也没有保存点。
问题不是 AI 写代码不够快,而是项目缺少共同上下文和停下来的规则。本课把项目准备成一个可控的协作场:先启动空项目,让 AI 读懂资料,再让它计划;每次只完成一个目标,运行验证、检查差异,确认后用 Git 留下本地记录。第 6 课会在这个项目上制作首页。
这一课完成后,你会得到什么
- 一个用 Next.js、TypeScript 和 Tailwind CSS 创建、能在本地浏览器打开的项目。
- 四份前置资料放在固定位置,AI 和你都能找到。
- 一份 TRAE 项目规则,写明技术栈、事实边界和修改节奏。
- 一个 MDX 内容目录,为后续文章与专题课程保存源文件。
- 一个本地 Git 初始提交;GitHub 账号或远端仓库可准备,但本课不推送、不部署。
先看全局:从课程资料到可以回退的代码
先确认这门课采用什么技术栈
技术栈就是一个项目用哪些相互配合的工具。当前 LUPY 课程站的实际配置是 Next.js 16.2.6、React 19.2.4、TypeScript 5、Tailwind CSS 4、MDX 3.1.1;内容保存在本地 .mdx 文件,由项目读取和渲染;依赖由 npm 和 package-lock.json 管理。主线选择这些现有技术,不让初学者先在框架清单里做无从判断的选择。Next.js 官方要求 Node.js 至少 20.9,并用 create-next-app 建项目;本仓库当前 package.json 的脚本是 npm run dev、npm run build、npm run lint。版本以后会变,照着自己的 package.json 和锁文件核对,不抄几年以前的命令。
| 名词 | 白话解释 | 本课只要会什么 |
|---|---|---|
| Node.js | 让 JavaScript/TypeScript 开发工具在电脑上运行的环境,不是网站本身 | 安装后能用 node -v 查看版本;Next.js 16 至少需要 20.9 |
| npm | 随 Node 一起使用的包管理器,负责安装项目需要的工具 | 在有 package.json 的目录运行 npm install,用 npm run dev 启动 |
| 项目目录 | 一份网站所有源码、说明和配置的根文件夹 | 在 TRAE 打开这一层,不要只打开 src |
| 开发服务器 | 临时在本机运行网站,让你边改边预览的程序 | 终端保持运行,在浏览器打开 http://localhost:3000 |
| TypeScript | 给 JavaScript 增加类型提示,帮助编辑器发现一些拼写或数据错误 | 暂时不学类型系统,先让 AI 按项目现有 .tsx 写法修改 |
| Tailwind CSS | 通过 HTML/JSX 上的类名组合排版、间距、颜色和响应式样式 | 知道项目已有 Tailwind;先复用,不混装另一套样式框架 |
| MDX | 可写 Markdown、也能嵌入组件的内容文件格式 | 把文章源文件放好;第 7 课再接内容列表与渲染 |
| Git | 保存项目不同时间状态的本地版本记录 | 会查看变化、保存一个提交、回到此前提交 |
| GitHub | 托管 Git 仓库的在线服务,可作为远端协作与备份位置 | 知道本地 Git 不等于 GitHub;本课不要求推送 |
项目目录是什么样
先用一张结构图认识要打开的“项目根目录”。本课建议把四份资料放进 docs/,文件名保持不变;等需要文章详情和专题课程时,MDX 源文放在 src/content/guides/。不要把自己写的资料放在 node_modules/ 或 .next/,这些目录会被工具重新生成。
| 路径 | 放什么 | 它的边界 |
|---|---|---|
docs/site-positioning-card.md | 目标读者、主题、内容承诺和事实/假设 | 给项目方向,不是首页宣传文案的唯一来源 |
docs/content-map.md | 栏目、内容条目、专题和课程的关系 | 没写过的文章要标计划,不能伪装为已发布 |
docs/conversion-path.md | 内容到真实行动和人工承接的路径 | 不能把未启用的表单或付款写成有效 |
docs/site-brief.md | 页面、优先级、设计方向、功能边界、验收 | 是 AI 的需求依据,不是让 AI 自行扩大范围的许可 |
.trae/rules/project-rules.md | 可重复使用的 AI 协作规则 | 约束协作,不代替每次任务的具体目标 |
src/app/ | Next.js 页面与共用外框 | page.tsx 对应 / 首页;layout.tsx 包住页面 |
src/content/guides/ | 后续可公开的 MDX 正文 | 第 5、6 课先建目录,不在这里写空文章 |
public/ | 公开图片、图标等静态文件 | 不放私密文件或未授权素材 |
package.json / 锁文件 | 依赖和脚本 / 实际解析出的依赖版本 | 修改依赖后锁文件要同步,不能随手删除 |
跟着做:让电脑和 AI 有同一份工作台
第一步:安装并检查 Node.js、npm 和 Git
**做什么:**从 Node.js 官网下载当前 LTS 安装包,安装后新开终端;从 Git 官网安装适合系统的 Git。**为什么现在做:**Node.js 运行 Next.js 工具,npm 安装代码依赖,Git 保存你的修改历史。**输入:**终端逐行运行 node -v、npm -v、git --version。**正常结果:**每条都打印版本号;Node 版本至少 20.9。**出错先检查:**提示“不是内部或外部命令”通常表示安装未完成或终端未重开;先重开终端,仍不行再检查安装目录是否加入 PATH。不要在 AI 生成的脚本中粘贴密码或令牌。
TRAE 主操作路径以 TRAE IDE 窗口为准;对话协作时使用支持计划的 Agent/Builder 工作流,不把 Chat 模式当作 Plan。若你的系统不符合 TRAE 官方当前要求,或账号暂时不可用,停在项目已能通过命令启动这一步,先解决环境/访问条件,不要因课程示意猜测界面。安装入口和支持的系统以官方快速开始页为准。
第二步:创建 Next.js 项目并启动
**做什么:**打开终端,进入你打算存放项目的父目录,执行:
npx create-next-app@latest personal-knowledge-site
向导中选择 TypeScript、ESLint、Tailwind CSS、App Router 和 src/ 目录;使用 @/* 导入别名。React Compiler 暂不需要;如果询问 Cache Components,就先采用 create-next-app 当前默认选项。**为什么现在做:**生成器会一并建立初始页面、配置和安装依赖,避免手工漏建关键文件。**正常结果:**出现 personal-knowledge-site 文件夹,里面有 package.json、锁文件、src/app/page.tsx 和 src/app/globals.css。**出错先检查:**命令失败时先看终端是否提示目录已存在、网络下载中断或 Node 版本不符;不要在已有文件的目录上覆盖。
进入项目目录并启动:
cd personal-knowledge-site
npm run dev
终端显示本地服务器地址后,在浏览器打开 http://localhost:3000。Next.js 官方快速开始也是用开发服务器并打开该地址;本机地址只在你这台电脑上工作,不是公开网站。保持这个终端窗口运行,结束时按 Ctrl+C。正常会看到生成器提供的初始 Next.js 页面。若浏览器打不开,确认终端仍在运行、当前目录是项目根目录;若端口被占用,Next 会报告另一个本地端口,就用终端提示的地址,或先关闭占用 3000 的旧开发服务器。
项目用 npm 时保留 package-lock.json;其他包管理器生成的锁文件不要混放。此课程跟着 LUPY 当前 npm 路线,不再安装 yarn 或 pnpm。Next、React 与 Tailwind 的具体补丁版由生成器和锁文件记录;需要检查时运行 npm ls next react typescript tailwindcss,不要单凭网上旧截图判断版本。
第三步:加入 MDX 内容能力并放入四份资料
**做什么:**在项目根目录安装与当前课程站相同主版本的 MDX 解析依赖,并建目录。**为什么现在做:**正文源文将以 .mdx 保存;即使这两课先做首页,也先让项目目录知道未来内容在哪。输入:
npm install @mdx-js/mdx@3.1.1 gray-matter@4.0.3 remark-gfm@4.0.1
然后新建 docs/ 和 src/content/guides/,把四份文件复制到 docs/,文件名分别为 site-positioning-card.md、content-map.md、conversion-path.md、site-brief.md。正常结果:package.json 与 package-lock.json 更新,四份文件可在编辑器直接打开。**出错先检查:**终端是否位于项目根目录,网络是否可访问 npm registry,是否有权限写入目录;不要为了消除报错删除锁文件或降级框架。MDX 现在只准备源文路径;第 7 课才接文章索引与详情。
第四步:在 TRAE 打开整个项目
**做什么:**在 TRAE 的 IDE 窗口选择“打开文件夹”,打开 personal-knowledge-site 根目录。**为什么现在做:**只打开 src/app 会让工具看不到 package.json、四份需求资料、锁文件和项目规则。**输入:**在编辑器确认能看到根目录的 package.json、docs/ 和 src/。**正常结果:**项目树能展开页面与资料,集成终端的当前路径就是项目根目录。**出错先检查:**不要误开外层父目录(它可能包含多个项目),也不要只开一个 page.tsx 文件。
TRAE 按 # 可引用 #File、#Folder 或 #Workspace。四份 Brief 小而重要,第一次要求时用 #File 明确逐一附加;项目结构问题可用 #Workspace,不要默认把 node_modules 全部塞进上下文。TRAE 文档说明 #Folder 的结果受工作区索引状态影响,因此遇到 AI 漏掉文件,先在 References/引用区域检查资料是否真的附上,不要盲目信任“我已经读过项目”。
第五步:建立项目规则
**做什么:**在项目中新建 .trae/rules/project-rules.md。可以在 TRAE IDE 的“设置 > 规则与记忆”创建项目规则,也可以按 TRAE 官方支持的目录手动新建 Markdown 文件。将其设为始终生效时,规则前置信息按 TRAE 自动生成的格式保留;如果手动编辑,检查 alwaysApply: true。**为什么现在做:**四份资料告诉 AI 网站要做什么,项目规则告诉它每次协作都必须守住什么。**正常结果:**你在 TRAE 项目规则面板或 #Rule 中能看到规则;一般聊天能遵守技术栈和边界。**出错先检查:**规则文件需位于当前项目下的 .trae/rules/,不是个人全局规则目录;若没有生效,按文档确认规则开关,或在对话中通过 #Rule 明确引用。
---
alwaysApply: true
---
# 个人知识站协作规则
- 当前技术栈以 package.json、锁文件和已有代码为准:Next.js App Router、TypeScript、Tailwind CSS、MDX、npm。
- 默认使用中文解释;不要因为任务方便而更换框架、包管理器或添加新依赖。
- 先阅读本轮明确附加的项目资料;不确定的经历、读者反馈、产品能力和数据标记为“待确认”,不得编造。
- 一次只处理一个明确目标。先复述、列计划并等待我确认;未确认计划前不改文件。
- 修改后先运行项目现有的验证命令,说明命令结果;我确认前不做 Git 提交、推送或部署。
- 不自行添加登录、会员、支付、数据库或 SaaS;不上传密钥、个人隐私或环境文件。
- 未经我同意,不修改本轮目标以外的页面、导航、课程或配置。
项目规则不是安全边界的替代品,也不保证模型永不犯错。每一轮任务仍要指定目标文件和验收条件。
第六步:让 AI 先复述,再计划
把下方 Prompt 复制到 TRAE Agent/Builder 对话中。首次用 # 加入四个 docs/ 文件、package.json 和项目规则。下面示例用方括号表示你在 TRAE 中应选择的上下文,不是特殊字符语法。
我正在建立个人知识库与订阅站。开始修改前,请通过我附加的文件理解项目:
[附加 docs/site-positioning-card.md]
[附加 docs/content-map.md]
[附加 docs/conversion-path.md]
[附加 docs/site-brief.md]
[附加 package.json 与 .trae/rules/project-rules.md]
请先只做理解和计划,不要修改文件、安装包、运行会改变项目的命令、Git 提交、推送或部署。
第一部分:用中文复述网站主要服务谁、内容是什么、主要行动是什么、第一版明确不做什么,并分别指出来源文件。
第二部分:查看 package.json 与项目目录,复述当前框架、包管理器、可用脚本和首页文件位置;未知项标“未确认”。
第三部分:为“让初始 Next.js 首页在本地运行并保留项目默认技术栈”提出最多 5 步计划。每一步列出将读取/修改的文件、运行命令、浏览器验收标准和回退方式。
不得新增页面、账户、支付、数据库、文章系统、依赖或设计素材。方案中有矛盾时先提问。
完成后停下来等我确认,不要自行执行。
Prompt 各段的作用:文件引用给事实来源;第一部分检查 AI 是否理解四份前置材料;第二部分让它对照真实配置,避免按记忆编造项目脚本;第三部分把工作变成可逐项审阅的计划;禁止项限制范围;最后的“停下”确保代码变化发生前有人工检查。确认后,才把计划中的第一项单独交给 AI 执行,并说明本轮只修改某个文件。
第七步:形成“小步修改—验证—检查差异”循环
**做什么:**一次只让 AI 完成一个可以在几分钟内检查的动作,例如“解释 src/app/layout.tsx 如何包住首页,不改文件”,之后再做“把浏览器标签标题改为项目名”。**为什么现在做:**若一次生成整站,发生问题时你无法定位是哪个需求造成。**输入:**一个目标文件、一条可观察结果、一组禁止项。**正常结果:**差异集中,验证失败也能说清失败发生在哪一步。**出错先检查:**如果 AI 一次改十多个文件,先停止,打开变更列表,要求解释每个文件的必要性;不能解释的部分先撤回这次修改,再拆小重做。
真实对话结构示意(不是工具截图或实际运行记录):
我:先阅读 Brief 和 package.json,只复述当前首页由哪个文件负责,不要改代码。
AI:Next.js App Router 的根页面由 src/app/page.tsx 导出;package.json 的 dev 脚本是 next dev。
我:正确。现在只把页签标题改成“我的知识站”,只改 src/app/layout.tsx;改后说明差异,不要提交。
AI:计划:检查 layout.tsx 的 metadata;仅更新 title;运行 npm run lint;报告变更。
我:计划符合范围,可以执行。
AI:已更新 title。检查结果:npm run lint 通过。改动只有 layout.tsx 的 title 字段。
我:我在浏览器确认页签标题正确,再检查差异并决定是否保存 Git 记录。
对话里 AI 声称“通过”不等于你已经验证。你仍要看到终端结束码/输出,浏览器行为也要亲自检查。未运行过的命令、只有计划没有执行的步骤,都应写成未完成。
第八步:用 Git 保存第一个可工作的状态
**做什么:**先确认项目有没有 .git;运行 git status --short 看文件,再保存初始版本。**为什么现在做:**提交是本地的可命名检查点,后续改坏页面时可以比较或回到该状态。输入:
git status --short
若提示不是 Git 仓库,再运行 git init;若已是仓库,不要重复初始化。随后检查 .gitignore 已忽略 node_modules/、.next/、本地环境文件;不要提交真实密钥、.env.local、密码或私人数据。确认要保存的文件后:
git add .
git status --short
git commit -m "chore: initialize personal knowledge site"
正常结果:git status --short 在提交后没有未保存修改;git log -1 --oneline 显示刚创建的提交。**出错先检查:**Git 提示缺少姓名/邮箱时,只为当前仓库设定 git config user.name "你的名字" 与 git config user.email "你的邮箱",再提交;提交前若发现秘密文件已暂存,先把它从暂存区移出并修正 .gitignore。Git 的本地提交不会自动上传 GitHub;本课停在本地检查点,远端连接和推送不是本课的交付。
小步开发与一次性大改有什么差别
| 小步循环 | 一次性大改 |
|---|---|
| 一个任务只改少数相关文件 | 同时改主页、导航、内容系统、账户与支付 |
| 先复述资料,用户确认计划 | 让 AI 自行补完所有未知条件 |
| 每步能在本地运行或检查 | 最后才运行,报错原因混在一起 |
| 看文件差异再决定是否提交 | 默认接受全部修改,发现问题后难定位 |
| Git 提交是人工确认的保存点 | AI 自行提交/推送或把错误覆盖掉 |
常见操作失败怎么查
| 现象 | 先检查 | 处理方向 |
|---|---|---|
node、npm 找不到 | 安装后是否新开终端;当前路径能否打印版本 | 重新打开终端;确认 Node 安装目录在 PATH;Node 低于 20.9 时换兼容版本 |
npm 安装一直失败或 npm run dev 找不到脚本 | 命令是否在项目根目录;package.json 是否有对应脚本;网络/代理/磁盘空间 | 先运行 pwd(PowerShell 用 Get-Location)和 npm run 核对;再看完整第一条错误,不盲目重复安装 |
| 依赖安装中断 | package-lock 是否存在;是否有 npm 进程仍在写入 | 等待或结束中断任务后,在项目根目录重新运行 npm install;不要删除锁文件尝试“清干净” |
| 3000 端口占用 | 是否有旧终端仍运行 npm run dev | 回到旧终端按 Ctrl+C,或使用 Next 输出的下一个本地端口 |
| 浏览器打不开首页 | 开发服务器终端是否还在运行;地址是否与输出一致 | 不关终端;复制它报告的 Local 地址;检查浏览器是否误用了旧端口 |
| AI 改太多或报错看不懂 | 变更列表和完整报错;发生错误的最近一步 | 暂停执行;让 AI 只解释根因并列最小修复,不让它同时重写;若差异混乱,使用 Git 查看/恢复该次变更 |
报错完整复制到对话中,包含刚运行的命令、终端路径、Node/npm 版本和错误第一行。不要只说“坏了”;也不要让 AI 在你不理解时运行删除、清理或覆盖项目的命令。
你现在应该看到什么
浏览器能打开 Next.js 初始首页,终端清楚显示项目在本机运行;TRAE 项目树里有四份资料、项目规则、src/app/ 和内容目录;Git 有一个本地初始提交。首页此时还是生成器模板完全正常,本课不要求已经有品牌视觉或文章列表。
本课任务与提交物
保存以下提交物:
- 项目目录
personal-knowledge-site/能运行npm run dev。 docs/site-positioning-card.md、docs/content-map.md、docs/conversion-path.md、docs/site-brief.md四个文件可打开。.trae/rules/project-rules.md或 TRAE 中等价的项目规则已启用。src/content/guides/目录已准备后续 MDX 内容。- 本地 Git 初始提交已创建,且工作区状态可解释。
开始开发前 Prompt就是本课第六步的完整 Prompt。可以修改主题、文件路径和第一项目标,但保留“只读理解—复述—计划—等确认”,不要把允许范围扩写成整站开发。
自检清单
- Node.js 至少 20.9,
node -v、npm -v、git --version都有输出。 - 技术栈与项目根目录配置一致,包管理器只有 npm 与
package-lock.json。 -
npm run dev本地页面能打开,终端没有被关闭。 - 四份前置资料和项目规则位于项目内、名字一致。
- TRAE 打开的是根目录,并能引用资料文件。
- AI 先复述并给计划;你能看变更、运行验证、控制是否提交。
-
.gitignore排除依赖、构建产物和私密环境文件;初始提交留在本机。
常见翻车点
- **把项目父文件夹当成根目录。**AI 找不到
package.json,终端命令也会失败。看文件树,必须同层看到package.json、src/和docs/。 - **四份资料只存在聊天里。**新对话或新工具无法稳定引用。把它们保存到项目并明确附加文件;使用
#Folder时确认索引已完成。 - **认为规则文件会替自己验收。**规则只提示模型行为,不能证明页面正常。照样看差异、终端结果和浏览器。
- **一开始安装很多组件、图标或动画库。**依赖增加排错面,当前没有需求。只保留 Next、React、TypeScript、Tailwind 和后续 MDX 所需依赖。
- **把每次修改自动交给 AI commit。**无法确认提交代表什么。提交前先看
git status和 diff,明确保存哪些文件。 - **把 GitHub 等同于 Git。**本地提交不会自动备份到网上;之后是否建立远端仓库、公开或推送由你决定,本课不要求上传代码。
下一课会怎么用到今天的成果
第 6 课会先让 TRAE 只读 site-brief.md 和四份资料,生成首页区块结构;你确认以后,再逐步实现首屏、主题入口和说明区。每一步都继续遵守本课建立的运行、检查差异与 Git 保存循环。
本课技术依据
- Next.js 官方 Installation 文档:核对 create-next-app 的 Next.js/App Router、TypeScript、Tailwind、ESLint 默认选项、Node.js 最低版本、开发服务器启动和
localhost:3000。 - TRAE 官方快速开始:核对当前 Windows/macOS/Linux 支持范围、打开本地文件夹以及 IDE/Agent 窗口的定位。
- TRAE 官方规则文档 与 上下文引用说明:核对项目规则目录、项目规则生效方式、
#File/#Folder/#Workspace的用途及代码索引提示。 - Git 官方用户手册:核对
git init、git add与git commit的本地版本记录流程。