微信小程序 + .NET 后端开发调试完整解决方案

🚀 微信小程序 + .NET 后端开发调试完整解决方案从零搭建到真机调试，涵盖内网穿透、图片加载、HTTPS 等所有坑点📖 写在前面最近在开发一个小程序项目时，后端使用 ASP.NET Core 8.0，前端是微信小程序。从开发环境搭建到真机调试，遇到了各种让人抓狂的问题：电脑上一切正常手机预览就是不行；API 请求成功了但图片死活加载不出来；真机调试局域网连接失败；内网穿透配置好了但总被微信拦截…花了几天时间彻底解决后，把这些经验整理出来，希望能帮你少走弯路。温馨提示：本文所有域名、IP 地址均为虚构示例，仅供学习参考。📋 目录项目架构概览开发环境搭建内网穿透方案图片资源加载问题真机调试终极指南完整解决方案总结1. 项目架构概览1.1 技术栈层级技术说明后端ASP.NET Core 8.0Web API 服务ORMEntity Framework Core 8.0数据库访问数据库SQL Server数据存储前端微信小程序原生移动端展示架构DDD + CQRS领域驱动设计1.2 项目结构OrangeGuitar.sln ├── OrangeGuitar.API # 表现层（Web API） │ ├── Controllers/ # 控制器 │ ├── Filters/ # 全局过滤器 │ ├── Middlewares/ # 中间件 │ └── Extensions/ # 扩展方法 ├── OrangeGuitar.Application # 应用层（业务逻辑） │ ├── Services/ # 应用服务 │ ├── Commands/ # CQRS 命令 │ ├── Queries/ # CQRS 查询 │ └── Handlers/ # 命令/查询处理器 ├── OrangeGuitar.Core # 领域层（核心实体） │ ├── Entities/ # 实体 │ ├── Enums/ # 枚举 │ ├── DTOs/ # 数据传输对象 │ └── Interfaces/ # 仓储接口 └── OrangeGuitar.Infrastructure # 基础设施层 ├── Data/ # DbContext ├── Repositories/ # 仓储实现 └── External/ # 外部服务（微信支付等）1.3 网络拓扑┌─────────────────────────────────────────────────────────────────┐ │ 开发环境网络 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 后端电脑 │ │ 开发电脑 │ │ 测试手机 │ │ │ │ 192.168.1.100│ │ 192.168.1.101│ │ 192.168.1.102│ │ │ │ .NET 8.0 │ │ 开发者工具 │ │ 微信客户端 │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ └───────────────────┼───────────────────┘ │ │ │ │ │ 同一 WiFi 网络 │ │ │ └─────────────────────────────────────────────────────────────────┘2. 开发环境搭建2.1 后端配置（ASP.NET Core）Program.cs 完整配置// OrangeGuitar.API/Program.csvarbuilder=WebApplication.CreateBuilder(args);// ============================================================// 1. 配置 Kestrel 监听地址// ============================================================// 开发环境：监听所有网络接口（允许外部设备访问）builder.WebHost.UseUrls("http://0.0.0.0:5251");// 生产环境：使用配置文件// builder.WebHost.UseConfiguration(builder.Configuration);// ============================================================// 2. 添加服务// ============================================================builder.Services.AddControllers(options={options.Filters.AddGlobalExceptionFilter();// 全局异常捕获options.Filters.AddValidationFilter();// 模型验证options.Filters.AddApiResponseFilter();// 统一响应包装});// ============================================================// 3. 配置静态文件服务（提供图片访问）// ============================================================builder.Services.AddHttpContextAccessor();// ============================================================// 4. 跨域配置// ============================================================builder.Services.AddCors(options={options.AddPolicy("AllowAll",policy={policy.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader();});});varapp=builder.Build();// ============================================================// 5. 使用中间件（顺序很重要！）// ============================================================// ✅ 第一步：CORS（必须放在最前面）app.UseCors("AllowAll");// ✅ 第二步：静态文件服务app.UseStaticFiles();// 自定义静态文件目录（如 assets_orange）app.UseStaticFiles(newStaticFileOptions{FileProvider=newPhysicalFileProvider(Path.Combine(builder.Environment.ContentRootPath,"Assets_Orange")),RequestPath="/assets_orange"});// ✅ 第三步：路由app.UseRouting();// ✅ 第四步：认证授权app.UseAuthentication();app.UseAuthorization();// ✅ 第五步：映射控制器app.MapControllers();app.Run();appsettings.json{"Logging":{"LogLevel":{"Default":"Information","Microsoft.AspNetCore":"Warning"}},"AllowedHosts":"*","ConnectionStrings":