buffalo项目首次运行必须同时执行go mod tidy和npm install（或yarn install），缺一不可：前者补全go子依赖如pop/v6，后者编译assets并注入哈希，否则buffalo dev将因缺失模块或webpack失败而panic。
go mod tidy 和 npm install 都不能跳过
Buffalo 项目启动前必须同时完成 Go 和 Node.js 两套依赖安装，缺一不可。只跑 go mod tidy 会导致 buffalo dev 启动时 panic：找不到 github.com/gobuffalo/packr/v2 或 github.com/gobuffalo/plush；只跑 npm install 则 Webpack 编译失败，buffalo dev 直接退出并报 “cannot find module ‘webpack’”。
原因在于 Buffalo 的构建流程是双阶段耦合的：Go 侧负责路由、中间件和数据库逻辑，Node.js 侧负责 assets 编译和哈希注入。即使你打算删掉 assets/，首次运行仍需 npm install，因为 buffalo dev 默认调用 npm run build，找不到 node_modules 就中断。
-
go mod tidy必须在项目根目录执行，它会补全pop/v6、buffalo-plugins等子依赖——CLI 生成的go.mod只声明顶层模块 -
npm install建议换成yarn install --frozen-lockfile --network-concurrency 16，尤其在国内网络下提速明显 - 若用
yarn，请先全局配置镜像：yarn config set registry https://registry.npm.taobao.org
database.yml 配置错误会导致 pop 连接器直接 panic
执行 buffalo db create 或 buffalo dev 时出现 dial tcp 127.0.0.1:5432: connect: connection refused，90% 是因为 config/database.yml 的 dialect 写错或数据库服务未就绪。
dialect 字段必须小写且拼写精确："postgres" ✅，"postgresql" ❌，"pg" ❌。Buffalo 使用 pop 连接器，它靠这个字符串匹配驱动注册表，拼错就无法加载驱动，后续所有 DB 操作都会 panic。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- PostgreSQL 用户注意：host 写
"localhost"可能走 Unix socket，建议统一用"127.0.0.1" - MySQL 用户必须加
sslmode: "false"和parseTime: "true"，否则连接成功但查询时间字段时报错 - 执行
buffalo pop create -a前，务必先用telnet 127.0.0.1 5432或nc -zv localhost 3306确认端口可通
GO_ENV 必须在 build 前设置，不是运行时才设
很多人把 GO_ENV=production buffalo build 写成 buffalo build && GO_ENV=production buffalo start，结果生产包里依然包含开发中间件，日志泄露敏感参数，甚至因 middleware.ParameterLogger 导致性能骤降。
Buffalo 的 app.Env 是编译期常量，由 GO_ENV 环境变量决定，并影响整个构建过程：development 中间件被排除、模板调试信息被剥离、静态资源压缩策略切换。运行时再设 GO_ENV 完全无效。
- Dockerfile 中应写
ENV GO_ENV=production，而不是靠docker run -e GO_ENV=production - CI/CD 流程中，
buffalo build命令前必须export GO_ENV=production - 别在
actions/app.go里写if os.Getenv("GO_ENV") == "production"—— 直接用app.Env == "production"，它更可靠且已被框架封装
session store 不校验连接，panic 发生在第一次 Save()
用 Redis 做 session 存储时，redis.NewStore("localhost:6379", "", "", "") 不会立即连接 Redis，错误要等到用户登录后调用 c.Session().Save() 才暴露为 panic，堆栈指向 redis.(*store).Save，排查困难。
根本原因是 NewStore 只初始化结构体，不执行 Ping。线上 Redis 地址配错或密码填错，服务启动时完全无提示，直到第一个用户触发登录。
- 务必在
app.go初始化 store 后加if err := store.Ping(); err != nil { log.Fatal("session store unreachable:", err) } - 若 Redis 需密码，第二个参数填密码字符串，第三个参数填 DB 编号（如
"0"），空字符串会被忽略 - 不要把
store声明为局部变量，确保它在整个生命周期内复用，否则连接池会反复新建销毁
buffalo dev 启动瞬间报错，而是在某个具体操作路径上突然崩溃，且错误位置离真实原因很远。
