eShop本地开发环境搭建与调试指南

1. 为什么需要本地运行eShop在电商系统开发过程中本地运行环境是每个开发者必须掌握的技能。eShop作为微软推出的开源电商解决方案其本地运行配置对于开发调试、功能测试和代码修改都至关重要。我见过太多新手开发者直接在生产环境上练手结果导致线上事故。本地运行能让你在安全的环境中自由实验不用担心影响真实用户。本地环境的最大优势在于即时反馈。当你修改一段商品分类逻辑时可以在秒级内看到效果而不需要经历漫长的CI/CD流程。根据我的经验一个配置得当的本地环境可以将开发效率提升3-5倍。特别是在调试支付流程这类复杂交互时本地环境允许你设置断点、查看实时日志这些都是云端环境难以提供的。2. 环境准备与工具选型2.1 硬件与基础软件要求在开始之前请确保你的开发机满足以下最低配置操作系统Windows 10/11 64位 或 macOS 10.15内存8GB推荐16GB存储空间至少20GB可用空间开发工具Visual Studio 2022社区版即可我强烈建议使用SSD硬盘因为eShop的依赖项较多机械硬盘在npm install时可能会让你等到怀疑人生。另外如果你使用Windows系统请确保已启用WSL2Windows Subsystem for Linux这能显著提升Docker的性能。2.2 核心组件安装eShop依赖几个关键组件安装顺序很重要Docker Desktop这是容器化运行的基础下载地址docker.com/products/docker-desktop安装后务必在设置中启用Kubernetes虽然本教程用不到但为后续扩展准备内存分配建议至少4GB在Docker设置→Resources中调整.NET 6.0 SDKeShop的后端核心dotnet --version # 验证安装如果版本低于6.0需从微软官网下载最新SDKNode.js前端开发必备node -v # 需要v14 npm -v推荐使用nvmNode Version Manager管理多版本注意所有安装路径不要包含中文或特殊字符这是90%安装失败的根源。我习惯统一使用C:\dev\tools这样的纯英文路径。3. 源码获取与初始化3.1 克隆仓库的正确姿势官方推荐从GitHub克隆最新代码git clone https://github.com/dotnet-architecture/eShopOnContainers.git cd eShopOnContainers但国内开发者可能会遇到网络问题这里分享我的备选方案使用Gitee镜像每日同步git clone https://gitee.com/mirrors/eShopOnContainers.git如果仍然缓慢可以直接下载ZIP包但不利于后续更新3.2 依赖安装的避坑指南进入项目根目录后先别急着运行有几个关键步骤# 还原NuGet包 dotnet restore # 安装前端依赖最易出错的环节 cd src/Web/WebSPA npm install常见问题处理npm ERR!删除node_modules和package-lock.json后重试证书错误执行npm config set strict-ssl false权限不足在命令前加sudoMac/Linux或用管理员身份运行Windows4. 数据库配置与启动4.1 容器化数据库部署eShop默认使用Docker容器运行数据库这是最便捷的方式docker-compose -f docker-compose.yml up -d mssql redis rabbitmq关键检查点使用docker ps查看容器状态日志检查docker logs eshop-mssql端口验证SQL Server: 1433Redis: 6379RabbitMQ: 56724.2 手动数据库配置备用方案如果容器方案不可用可以手动安装SQL Server下载Developer版本修改连接字符串// src/Infrastructure/Data/ConfigSettings.json { ConnectionString: Serverlocalhost;DatabaseMicrosoft.eShopOnContainers.CatalogDb;User Idsa;PasswordYourStrongPassw0rd; }执行初始化脚本src/Setup/DbScripts下的SQL文件5. 服务启动与调试5.1 后端服务启动推荐使用Visual Studio的启动配置打开eShopOnContainers-ServicesAndWebApps.sln设置启动项目为Identity.APICatalog.APIBasket.API按F5启动调试控制台启动方式适合轻量级开发cd src/Services/Catalog/Catalog.API dotnet run5.2 前端应用启动SPA应用需要单独启动cd src/Web/WebSPA npm start启动后访问http://localhost:42005.3 网关配置API网关是连接前后端的关键cd src/ApiGateways/Web.Bff.Shopping/apigw dotnet run配置文件中需要检查# src/ApiGateways/Web.Bff.Shopping/apigw/config.yaml routes: - uri: http://localhost:5202 upstreamPathTemplate: /api/v1/catalog/{everything}6. 常见问题排查手册6.1 端口冲突解决方案错误现象Address already in use解决方法查找占用进程netstat -ano | findstr :5202终止进程或修改配置// Properties/launchSettings.json applicationUrl: http://localhost:52036.2 跨域问题CORS处理前端报错Access-Control-Allow-Origin后端解决方案// Startup.cs services.AddCors(options { options.AddPolicy(CorsPolicy, builder builder.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader()); });6.3 身份认证失败错误日志Invalid token检查步骤确认Identity服务已启动验证配置// appsettings.json IdentityUrl: http://localhost:5105清除浏览器缓存或使用隐私模式7. 性能优化技巧7.1 启动加速方案初始启动可能很慢试试这些技巧关闭不需要的服务如Payment、Ordering使用内存数据库docker-compose -f docker-compose.yml up -d redis预编译视图dotnet publish -c Release7.2 资源占用优化当内存不足时限制Docker内存# docker-compose.override.yml mssql: deploy: resources: limits: memory: 2GB关闭诊断工具// appsettings.Development.json Diagnostics: { Enable: false }8. 开发调试高级技巧8.1 热重载配置.NET 6支持热重载无需重启dotnet watch run在.cs文件中保存更改时会自动刷新8.2 数据库探查器推荐使用Azure Data Studio连接本地SQL Server执行查询分析SELECT * FROM sys.dm_exec_query_stats CROSS APPLY sys.dm_exec_sql_text(sql_handle)8.3 前端调试技巧Chrome开发者工具的高级用法网络请求过滤domain:localhost本地代码映射// webpack.config.js devtool: source-mapRedux状态监控安装Redux DevTools扩展9. 生产环境准备虽然本文聚焦本地开发但有几个生产环境注意事项值得提前了解配置分离将敏感信息移出appsettings.jsondotnet user-secrets set ConnectionStrings:Default Serverprod-db;...健康检查services.AddHealthChecks() .AddSqlServer(Configuration[ConnectionString]) .AddRedis(Configuration[Redis]);日志聚合建议配置SerilogSeqdocker run -d --name seq -p 5341:80 datalust/seq10. 扩展学习路径当你能熟练运行本地环境后可以进一步探索微服务架构分析src/BuildingBlocks领域驱动设计实现src/Services/Ordering前端架构优化src/Web/WebSPA/src/app推荐修改的第一个简单功能尝试在商品目录页添加新品标签修改Catalog.API和WebSPA项目