Makefile 作为项目入口：把长命令变成 make dev

一个项目用到第三周，启动命令就会开始失控：先 source 虚拟环境，再 export 一两个变量，然后等待数据库就绪，最后启动服务。这些步骤写在 README 里，新人照着敲还是会漏一步。把项目入口收敛到一个 Makefile 里，是成本最低的解法。

一、为什么是 Makefile

make 在几乎所有 Linux/macOS 开发机上预装，不像各种 task runner 还要额外引入运行时。Makefile 的核心规则「目标: 依赖 + 命令」天然能表达先起数据库、再跑迁移、最后启动服务这类顺序关系，并且 make 只在依赖变化时才重新执行，能省掉不少重复等待。对中小项目来说，它比 npm scripts 更通用，比文档里的复制粘贴更不容易出错。

二、最小可用模板

在项目根目录放一个 Makefile，注意命令行必须用 Tab 缩进：dev 目标里先激活虚拟环境再启动服务；test 目标跑 pytest 并在首个失败处停止；lint 目标跑代码检查；另加一个 clean 目标清理缓存目录。第一行用 .PHONY 声明这些目标不对应真实文件，避免目录下恰好有同名文件时 make 拒绝执行。这样 README 里的「环境准备加三条命令」就收敛成一句话：make dev。

三、几个实用技巧

第一，常用命令提为变量放在头部，例如 COMPOSE := docker compose，后面统一引用，换工具时只改一行。第二，写一个 help 目标，用 awk 从注释里自动生成帮助信息，让 make help 代替 README 查表。第三，长流程拆成小目标：db-up、migrate、run 各自独立，dev 用依赖把它们串起来，单步调试也更方便。第四，Windows 用户建议在 WSL 或 Git Bash 里运行 make，原生 cmd 对 Tab 缩进和 source 命令的兼容性都不好。

四、一个提醒

Makefile 不是万能的：它擅长命令编排，不擅长复杂条件逻辑。当逻辑开始出现多层判断和循环时，果断抽到独立脚本里，Makefile 只保留一行调用。保持每个目标简单到一眼看懂，这个项目入口才有长期价值。