Skip to content

docs: 在 README 增加启动后端的两种环境变量加载方式#30

Merged
longsizhuo merged 2 commits intoInvolutionHell:mainfrom
F1sh2712:docs/local-env-setup-guide
May 10, 2026
Merged

docs: 在 README 增加启动后端的两种环境变量加载方式#30
longsizhuo merged 2 commits intoInvolutionHell:mainfrom
F1sh2712:docs/local-env-setup-guide

Conversation

@F1sh2712
Copy link
Copy Markdown
Contributor

@F1sh2712 F1sh2712 commented May 8, 2026

What

在 README 的"启动后端服务"章节增加两种环境变量加载方式的说明。

Why

./mvnw spring-boot:run 不会自动读取 .env 文件,但 README 没有说明启动前如何加载环境变量。新贡献者按 README 走会因为 Java 进程拿不到 PGPASSWORD 等变量而启动失败:
The server requested SCRAM-based authentication, but no password was provided.

Closes #25

How

把"启动后端服务"章节从单一命令扩展为两种方式:

  • 方式 1:维护者团队内部使用的 set -a && . ./.env && set +a(macOS / Linux)
  • 方式 2:IntelliJ IDEA + EnvFile 插件

set -a 那一行附了一句简短解释,避免对该 shell 语法不熟的读者困惑。

Testing

实测两种方式都能成功启动后端:

  • 方式 1:在 命令行 里执行 set -a && . ./.env && set +a 后跑 ./mvnw spring-boot:runStarted BackendApplication
  • 方式 2:IDEA 配好 EnvFile 后点绿色三角 → Started BackendApplication

未启用任何方式直接跑 ./mvnw spring-boot:run 会复现 SCRAM 认证失败,验证 README 新说明的必要性。

Copy link
Copy Markdown
Member

@longsizhuo longsizhuo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

方向对,方式 1 的 snippet 在 bash/zsh/WSL/Git Bash 实测都跑通,方式 2 EnvFile 也是社区主流方案。

两个建议:

1. 补一段 Windows PowerShell 路径

issue #25 problem 4 你自己也提到了 "Windows PowerShell 需手动设置或写脚本",你在 Windows 11 + IDEA 上应该最有发言权。但现在 PR 里只有 bash 和 IDEA 两条,纯命令行用 PowerShell 的 Windows 用户(尤其是不装 IDEA 的)还是没文档可看。

可以加一段类似:

**方式 3:Windows PowerShell**

\`\`\`powershell
Get-Content .env | Where-Object { $_ -match '^[^#].+=' } | ForEach-Object {
    $name, $value = $_ -split '=', 2
    [Environment]::SetEnvironmentVariable($name.Trim(), $value.Trim())
}
./mvnw spring-boot:run
\`\`\`

2. 提一下 CRLF 坑

Windows 下用 Notepad/VSCode 默认 CRLF 编辑过的 .env,在 Git Bash / WSL 里 . ./.env 会把 \r 一起带进变量值,后面 JDBC 拼 URL 时报奇怪的连接错(PGHOST=localhost\r 解析出来的主机名带回车)。

可以在方式 1 末尾补一句:

如果你用 Windows 编辑器改过 .env,先 dos2unix .env 或在编辑器里把行尾改成 LF,否则 . source 会把 \r 带进环境变量值。


不阻塞合并,作为 follow-up 提交也行。当前内容对绝大多数 macOS/Linux 新人已经够用。

- 方式 1 标题明确为 macOS/Linux/WSL/Git Bash,避免 Windows 用户误用
- 新增方式 2 PowerShell 解析 .env 的 snippet
- 警告 .env CRLF 会被 `. ./.env` 把 \r 带进变量值的坑
- 方式 2 重命名为方式 3,标 "跨平台"
Copy link
Copy Markdown
Member

@longsizhuo longsizhuo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@F1sh2712 也直接在你分支上 push 了一个补丁 commit (762c058) 加了 Windows PowerShell 路径和 CRLF 警告,凑齐 issue #25 problem 4 提到的"macOS/Linux/Windows PowerShell/IDE"四种路径。

主体内容还是你写的(bash 三件套 snippet + IDEA EnvFile),这两个的实测和落点都对。可以合了。

@longsizhuo longsizhuo merged commit 2d902d0 into InvolutionHell:main May 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

新贡献者本地启动后端时遇到的多个问题汇总

2 participants