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

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

从零搭建到真机调试，涵盖内网穿透、图片加载、HTTPS 等所有坑点

📖 写在前面

最近在开发一个小程序项目时，后端使用 ASP.NET Core 8.0，前端是微信小程序。从开发环境搭建到真机调试，遇到了各种让人抓狂的问题：电脑上一切正常手机预览就是不行；API 请求成功了但图片死活加载不出来；真机调试局域网连接失败；内网穿透配置好了但总被微信拦截…

花了几天时间彻底解决后，把这些经验整理出来，希望能帮你少走弯路。

温馨提示： 本文所有域名、IP 地址均为虚构示例，仅供学习参考。

📋 目录

1. 项目架构概览
2. 开发环境搭建
3. 内网穿透方案
4. 图片资源加载问题
5. 真机调试终极指南
6. 完整解决方案总结

1. 项目架构概览

1.1 技术栈

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.cs
var builder = 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.Add<GlobalExceptionFilter>();  // 全局异常捕获
    options.Filters.Add<ValidationFilter>();       // 模型验证
    options.Filters.Add<ApiResponseFilter>();      // 统一响应包装
});

// ============================================================
// 3. 配置静态文件服务（提供图片访问）
// ============================================================
builder.Services.AddHttpContextAccessor();

// ============================================================
// 4. 跨域配置
// ============================================================
builder.Services.AddCors(options =>
{
   
   
    options.AddPolicy("AllowAll", policy =>
    {
   
   
        policy.AllowAnyOrigin()
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
});

var app = builder.Build();

// ============================================================
// 5. 使用中间件（顺序很重要！）
// ============================================================

// ✅ 第一步：CORS（必须放在最前面）
app.UseCors("AllowAll");

// ✅ 第二步：静态文件服务
app.UseStaticFiles();

// 自定义静态文件目录（如 assets_orange）
app.UseStaticFiles(new StaticFileOptions
{
   
   
    FileProvider = new PhysicalFileProvider(
        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":