一、部署环境配置不当
部署时最常见的问题就是环境没配好。比如服务器上缺少运行时组件，或者版本不匹配。
示例场景：
# 技术栈：.NET Core 3.1 + Linux
# 错误现象：运行时报错"Could not find the required version of .NET Core"
# 原因：服务器只安装了.NET Core 2.1运行时
sudo apt-get install dotnet-runtime-3.1 # 解决方案：安装对应版本运行时
注意事项：
- 生产环境需严格匹配开发环境的SDK和运行时版本
- 可通过
dotnet --info命令验证环境
二、依赖项缺失或冲突
NuGet包没正确还原，或者不同包之间存在版本冲突，都会导致部署失败。
示例（C#项目文件片段）：
<!-- 技术栈：.NET 6 + NuGet -->
<ItemGroup>
<PackageReference Include="Newtonsoft.Json" Version="13.0.1" /> <!-- 显式指定版本 -->
<PackageReference Include="Dapper" Version="2.0.123" />
</ItemGroup>
典型问题：
- 未执行
dotnet restore - 私有NuGet源未配置
- 间接依赖的包版本被其他包覆盖
三、文件权限问题（Linux部署场景）
在Linux上部署时，常遇到文件不可写或执行权限不足的情况。
完整示例：
# 技术栈：.NET Core + Nginx反向代理
# 部署目录权限设置（以/var/www/myapp为例）
sudo chown -R www-data:www-data /var/www/myapp # 修改属主
sudo chmod -R 755 /var/www/myapp # 设置权限
sudo setfacl -R -m u:www-data:rwx /var/www/myapp # 更精细的ACL控制
关键点：
- 应用程序需要logs、temp等目录的写权限
- 使用systemd服务时需注意服务账户权限
四、数据库连接配置错误
超过60%的部署失败与数据库连接相关，尤其是生产环境配置覆盖问题。
C#示例：
// 技术栈：.NET Core + MySQL
// 错误配置示例（appsettings.json）
{
"ConnectionStrings": {
"Default": "Server=localhost;Database=mydb;User=dev;Password=123"
// 生产环境应该使用环境变量或密钥管理
}
}
// 正确做法（Program.cs）：
builder.Configuration.AddEnvironmentVariables();
var connection = builder.Configuration.GetConnectionString("Default");
最佳实践：
- 永远不要在代码中硬编码连接字符串
- 使用Azure Key Vault或AWS Secrets Manager管理敏感信息
五、未处理的运行时异常
有些错误只在特定运行时环境触发，比如文件路径大小写问题。
完整案例：
// 技术栈：.NET Core + Docker
// 问题代码：
var config = File.ReadAllText("/app/config/settings.json"); // Linux严格区分大小写
// 修复方案：
var configPath = Path.Combine(AppContext.BaseDirectory, "config", "settings.json");
if (!File.Exists(configPath)) throw new FileNotFoundException("配置文件缺失");
调试技巧：
- 使用
try-catch包装高危操作 - 记录详细日志到文件系统或ELK
六、发布包不完整
使用dotnet publish时漏掉关键文件会导致运行时失败。
PowerShell示例：
# 技术栈：.NET 7 + Windows
# 错误发布方式：
dotnet publish -c Release -o ./publish # 可能遗漏wwwroot静态文件
# 正确做法：
dotnet publish -c Release -o ./publish --no-build /p:CopyOutputSymbolsToPublishDirectory=false
必须检查：
- 确认publish文件夹包含所有dll、json配置文件
- 静态文件是否包含
<Content>标记
七、端口绑定冲突
当多个服务争夺同一端口时，应用会启动失败。
Linux排查示例：
# 技术栈：.NET Core + Kestrel
sudo netstat -tulnp | grep 5000 # 检查端口占用
kill -9 <PID> # 终止占用进程
# 更好的方案：在Program.cs配置备用端口
webBuilder.UseUrls("http://*:5000", "http://*:5001");
扩展方案：
- 使用Nginx反向代理处理端口冲突
- 在Docker中通过
-p参数映射外部端口
八、未考虑跨平台差异
Windows开发直接部署到Linux时可能遇到路径分隔符等问题。
C#兼容性示例：
// 技术栈：跨平台.NET Core
// 错误写法：
string filePath = "data\\export\\report.csv";
// 正确写法：
string filePath = Path.Combine("data", "export", "report.csv");
特别注意：
- 文件路径使用
Path.Combine() - 换行符使用
Environment.NewLine - 时区处理使用
DateTimeOffset
九、日志配置缺失
没有正确的日志记录会导致部署失败时无法诊断。
Serilog配置示例：
// 技术栈：.NET 6 + Serilog
Host.CreateDefaultBuilder(args)
.UseSerilog((ctx, config) => {
config.MinimumLevel.Debug()
.Enrich.FromLogContext()
.WriteTo.Console()
.WriteTo.File("/var/log/myapp/log-.txt",
rollingInterval: RollingInterval.Day);
})
日志分级建议：
- Development环境：Debug级别
- Production环境：Warning级别以上
十、资源限制问题
服务器内存、磁盘空间不足会导致不可预知的失败。
Docker部署示例：
# 技术栈：.NET Core + Docker Compose
version: '3'
services:
myapp:
image: myapp:latest
deploy:
resources:
limits:
cpus: '2'
memory: 1GB
restart: unless-stopped
监控指标：
- 内存使用率（通过
dotnet-counters监控） - 线程池饥饿情况
- GC回收频率
总结与最佳实践
通过200+次部署经验总结，建议采用以下标准化流程：
预检清单：
- 运行时版本验证
- 磁盘空间检查
- 防火墙规则确认
部署策略：
- 蓝绿部署降低风险
- 使用CI/CD流水线自动化
回滚方案：
- 保留最近3个可运行版本
- 数据库迁移脚本需兼容回滚
监控体系：
- 健康检查端点（/health）
- Prometheus + Grafana监控看板
记住：成功的部署 = 80%的准备 + 15%的执行 + 5%的运气。遇到问题时，先从日志找线索，再检查环境差异，最后考虑代码兼容性。
评论