修改Docker挂载的.env文件时FastAPI服务Windows运行失败问题

核心原因 #

Windows NTFS文件系统与Linux容器的文件系统交互时，若容器内进程打开了挂载的单个.env文件，Windows会锁定该文件，禁止容器执行重命名/替换（rename）这类操作，而macOS的APFS无此严格限制，因此出现跨平台差异。

实用解决方案 #

• 直接修改文件内容，而非替换文件
  不要用os.rename这类替换整个文件的操作，而是将修改后的内容直接写入原文件，绕开文件锁定限制：

  # 示例：更新.env内容的正确方式
  updated_env = {
      "KEY1": "new_value1",
      "KEY2": "new_value2"
  }
  # 将键值对格式化为.env格式的字符串
  env_content = "\n".join([f"{k}={v}" for k, v in updated_env.items()])
  # 直接写入原文件
  with open("/app/.env", "w") as f:
      f.write(env_content)
  

• 避免长期持有.env文件句柄
  显式将.env内容读取到内存后再加载，释放文件句柄，减少锁定概率：

  from dotenv import dotenv_values
  
  # 读取文件内容到内存
  with open("/app/.env", "r") as f:
      env_raw = f.read()
  # 从内存内容加载环境变量
  env_vars = dotenv_values(stream=env_raw)
  # 若需要加载到系统环境变量，可改用：
  # from dotenv import load_dotenv
  # load_dotenv(stream=env_raw, override=True)
  

• 改用目录挂载替代单个文件挂载
  Windows对目录挂载的文件锁定限制远低于单个文件挂载，修改挂载方式：
  原命令（单个文件挂载）：

  docker run -v C:\your\path\.env:/app/.env your-image
  

  修改为（挂载.env所在目录）：

  docker run -v C:\your\path\env_folder:/app/env_folder your-image
  

  容器内操作路径改为/app/env_folder/.env即可。

• 检查Docker文件共享权限
  确保Docker Desktop已开启对应磁盘的文件共享（路径：Settings > Resources > File Sharing），权限配置异常也可能引发类似文件操作错误。

内容的提问来源于stack exchange，提问作者Marcos Mussio