asp.net core docker镜像构建需启用dockersupportenabled、sdk与runtime镜像版本严格对齐、正确配置环境变量和端口暴露，否则会导致运行时找不到框架、配置失效或服务不可达。
ASP.NET Core项目必须启用Docker支持才能生成正确镜像
Visual Studio自动生成的 Dockerfile 依赖项目属性中 DockerSupportEnabled 为 true，否则发布时不会复制 bin/Release/net8.0/publish 下的运行时依赖。手动添加时容易漏掉 <dockerdefaulttargetos>Linux</dockerdefaulttargetos>，导致 Windows 容器镜像无法在 Linux 主机运行。
- 检查
.csproj文件是否含<dockersupportenabled>true</dockersupportenabled> - 确认目标框架是
net8.0（或对应版本），且未混用Microsoft.NET.Sdk.Web和Microsoft.NET.Sdk - 若用 CLI 构建，必须先执行
dotnet publish -c Release -o ./publish，再用docker build引用该目录
多阶段构建里 SDK 镜像和 Runtime 镜像版本必须严格对齐
常见错误是 FROM mcr.microsoft.com/dotnet/sdk:8.0 对应 FROM mcr.microsoft.com/dotnet/aspnet:8.0-jammy，但实际用了 7.0-jammy —— 运行时找不到匹配的 Microsoft.AspNetCore.App 共享框架，启动报错 It was not possible to find any compatible framework version。
- SDK 和 Runtime 镜像标签中的主版本号（如
8.0）必须一致 - 推荐用带
-jammy后缀的镜像（Ubuntu 22.04），避免-focal在新 Docker Desktop 上因 glibc 版本不兼容而启动失败 -
dotnet --list-runtimes在容器内执行可验证已安装的运行时是否包含Microsoft.AspNetCore.App 8.0.x
环境变量和配置文件在容器中失效的典型原因
本地 appsettings.Development.json 不会自动加载，ASPNETCORE_ENVIRONMENT 环境变量没设或拼写错误（比如写成 ASPNET_ENVIRONMENT）会导致配置回退到默认值，数据库连接字符串、JWT 密钥等全错位。
- 启动容器时必须加
-e ASPNETCORE_ENVIRONMENT=Production（或对应环境名） - 敏感配置不要硬编码进
Dockerfile，改用--env-file或 Kubernetes Secret 挂载 - 挂载配置文件时路径要匹配：容器内
/app/appsettings.json对应宿主机./configs/appsettings.prod.json，且需在ENTRYPOINT前用COPY或VOLUME确保可见
端口暴露和健康检查配置不到位导致服务不可达
镜像构建后能 docker run -d 起来，但 curl localhost:5000/health 超时，多数是因为没暴露端口或没配 EXPOSE + docker run -p 组合，或者 HealthCheck 路由未注册、中间件顺序错误。
-
Dockerfile中写EXPOSE 80仅作文档用途，真正生效靠docker run -p 8080:80 - ASP.NET Core 默认监听
http://+:80，若代码里调了UseUrls("http://localhost:5000")，容器内localhost指向自身，外部请求无法进入 - 健康检查建议用
dotnet-monitor或内置AddHealthChecks()，并在Program.cs中调用MapHealthChecks("/health")
最常被忽略的是容器内时区和日志输出——没加 ENV TZ=Asia/Shanghai 会导致日志时间错乱；没把 Console.WriteLine 输出重定向到 stdout（即没禁用 Systemd 日志驱动），docker logs 就看不到任何内容。
