五看一跑：小白也能看懂的工程运行与部署手册
作者：给未来的自己 适用人群：第一次接触代码仓库、不会部署、害怕报错的人 目标：拿到任何项目后，知道怎么判断、怎么运行、怎么部署、怎么排错
0. 先建立一个正确心态
你不需要“看懂所有代码”才能跑项目。 你只需要先搞定这 3 件事：
- 这个项目用什么技术写的（Node/Python/Java…）
- 它要什么环境和配置（版本、环境变量、数据库）
- 正确的启动命令是什么（dev/build/start）
一句话：先把项目跑起来，再慢慢理解细节。
1. 五看一跑（核心流程）
一看：README.md（最重要）
你先找根目录的 README.md，重点扫这几段：
Quick Start/Getting StartedInstall/Run/BuildEnvironment Variables/.envDeploy/Docker/Vercel
如果 README 有命令，优先信 README。
常见命令长这样：
npm install
npm run dev或：
pip install -r requirements.txt
python app.py二看：项目类型文件（判断技术栈）
你要先判断这是什么项目，再决定怎么跑。
- 看到
package.json：通常是 Node 前端/全栈项目 - 看到
requirements.txt或pyproject.toml：通常是 Python 项目 - 看到
pom.xml/build.gradle：通常是 Java - 看到
go.mod：Go - 看到
Cargo.toml：Rust
小抄：文件 → 常用命令
- Node：
npm install→npm run dev/npm run build - Python：建虚拟环境 →
pip install -r requirements.txt→python ... - Java：
mvn spring-boot:run或./gradlew bootRun - Go：
go run main.go
三看：启动脚本（知道具体该跑什么）
以 Node 为例，看 package.json 的 scripts：
dev：开发模式启动（改代码会热更新）build：打包生产文件start/preview：运行生产结果test：跑测试
所以，最稳妥顺序通常是：
npm installnpm run dev- 如果要部署再
npm run build
四看：环境变量和配置
很多项目“能启动但不能用”，通常是环境变量没配。
你要找：
.env.example.env.local- README 里的环境变量说明
常见变量：
API_KEY：接口密钥API_URL：接口地址DATABASE_URL：数据库连接PORT：端口
做法：
- 复制模板：
cp .env.example .env.local - 按注释填写值
- 重启服务
五看：部署线索文件
你要识别“项目希望你怎么部署”。
- 有
Dockerfile/docker-compose.yml：优先 Docker 部署 - 有
vercel.json：通常可 Vercel 一键部署 - 有
netlify.toml：通常可 Netlify 部署 - 纯前端项目通常部署
dist/（静态文件）
一跑：先本地跑通，再谈上线
本地跑通的标准：
- 终端无致命报错
- 浏览器能打开本地地址（如
http://localhost:5173） - 核心功能能点通一条流程
你可以记这个最小动作：
# Node 项目常用
npm install
npm run dev如果成功，再做：
npm run build
npm run preview这相当于“本地模拟生产环境”。
2. 小白排错四件套（90% 问题都在这）
问题 1：依赖装不上
典型报错：权限、网络、Node 版本不对。
排查顺序：
- 看版本：
node -v、npm -v - 看错误关键词：
EACCES、EPERM、ENOTFOUND - 清理重装：删
node_modules+ 锁文件后再装（谨慎）
问题 2：端口被占用
典型报错：port already in use。
做法：
- 换端口启动（例如 4173）
- 或结束占用端口的旧进程
问题 3：前端能开，接口报错
典型表现：页面开了，但按钮请求失败。
常见原因：
- API Key 没填
- API URL 填错
- 跨域（CORS）被拦截
做法：
- 检查
.env和页面设置 - 看浏览器控制台 Network 报错
- 本地开发使用代理（如果项目支持）
问题 4：build 成功但部署后白屏
常见原因：
- 前端
base路径配置不对 - 静态资源没上传完整
- 部署平台路由配置不对
做法：
- 先本地
npm run preview看是否正常 - 对比线上和本地控制台报错
- 检查部署平台构建命令和输出目录
3. 你可以直接套用的“通用实战模板”
模板 A：拿到新项目第一天
# 1) 进入项目
cd 项目目录
# 2) 看文档
# 打开 README.md
# 3) 安装依赖
npm install
# 4) 启动开发服务
npm run dev
# 5) 打开浏览器访问 README 提供的地址模板 B：准备上线前
# 1) 生产构建
npm run build
# 2) 本地预览生产包
npm run preview
# 3) 确认没问题后再部署 dist/模板 C：遇到错误时的提问格式（高效求助）
你给别人发问题时，尽量包含：
- 你执行了什么命令
- 完整报错截图或文本
- 你的系统和版本（macOS、Node 版本）
- 你已经尝试过什么
这样别人更容易一次性帮你解决。
4. 结合你这个项目的真实示例（gpt_image_playground）
你这个仓库是典型 Vite 前端项目：
- 关键文件：
package.json - 常用脚本：
dev/build/preview - 本地运行：
npm install
npm run dev- 生产预览：
npm run build
npm run preview打开页面后还需要在右上角配置 API 信息（API URL / API Key），否则界面能打开但无法真正生图。
5. 最后给你的“30 秒口令”
以后拿到新项目，先默念：
- 看 README
- 看项目类型
- 看 scripts
- 看环境变量
- 看部署文件
- 先本地跑通
你只要按这 6 步做，已经超过很多“只会复制命令”的人了。