项目说明文件：先看怎样启动，再看它依赖什么

JavaScript 项目先找 package.json

一个真实精简版本：

{
  "name": "ai-message-board",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "test": "vitest run"
  },
  "dependencies": {
    "react": "^19.0.0",
    "express": "^5.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vite": "^7.0.0",
    "vitest": "^3.0.0"
  },
  "packageManager": "pnpm@10.0.0"
}

name

项目或包名称。它不一定等于 GitHub 仓库名，也不决定网站域名。

private

true 常用于防止误把应用发布到 npm 注册表。它不等于 GitHub 私有仓库，也不是登录权限。

type: module

说明 Node.js 怎样解释 JavaScript 模块语法。看到 import/export 相关错误时，这个字段可能有关。

scripts

项目提供的标准任务入口。

dev      开发服务器，通常用于本地边改边看
build    生产构建，部署前检查和生成产物
test     运行测试
lint     检查代码规则
start    常用于运行生产服务器

运行：

pnpm dev
pnpm build

具体名称不是法律。有的项目叫 serve，所以先读 scripts。

dependencies

应用运行时需要的包。例如 React 页面运行需要 react，Express 后端运行需要 express。

devDependencies

开发、检查、测试和构建时使用的工具，例如 TypeScript、Vite、Vitest。

“开发依赖”不等于不重要。部署平台执行构建时仍可能需要它们。

packageManager

告诉协作者使用哪个包管理器和版本：

"packageManager": "pnpm@10.0.0"

再结合 pnpm-lock.yaml，不要混用 npm。

版本符号怎样读

"1.2.3"     固定这个版本
"^1.2.3"    通常允许不改变主版本的兼容更新
"~1.2.3"    通常允许补丁版本更新
"latest"    随时间变化，不利于重复环境

锁文件会记录实际安装结果。初学阶段不要为了“更新到最新”一次升级全部依赖。

Python 项目的 requirements.txt

Flask==3.1.0
requests==2.32.0
psycopg[binary]==3.2.0

每行通常是包和版本要求。安装：

pip install -r requirements.txt

它不保存启动命令，所以仍要看 README、app.py、pyproject.toml 或平台配置。

pyproject.toml 是什么

现代 Python 项目可能把项目信息、依赖和工具配置放在 pyproject.toml。看到它不要再假设 requirements.txt 一定是唯一清单。

读陌生项目的顺序

README
  ↓ 怎样安装和启动
packageManager + 锁文件
  ↓ 用 npm、pnpm 还是 Yarn
scripts
  ↓ dev、build、test 的真实命令
dependencies
  ↓ 使用哪些框架和服务
环境变量模板
  ↓ 启动前还缺什么配置

常见错误

Missing script: dev

package.json 的 scripts 没有 dev。先看真实脚本名，不要凭习惯运行。

Cannot find package

依赖未安装、未记录、版本不兼容或导入名错误。

改了 package.json 但没更新锁文件

应该使用对应包管理器安装或删除包，让 package.json 和锁文件一起更新。

只把 node_modules 复制给别人

不可靠。应该提交清单和锁文件，让对方在自己的环境安装。

npm run build 中的 build 是 npm 固定命令吗？

答案：不是。npm 会在当前项目 package.json 的 scripts 中查找 build，并执行该项目定义的内容。