项目使用常见问题及解答

一、程序运行时提示数据库连接错误

A：九成是连接字符串没改。找到配置文件把服务器名、数据库名、账号密码换成你自己的：

• Java（Spring Boot）：src/main/resources/application.yml 或 application.properties 里的 spring.datasource
• PHP：Laravel 看根目录的 .env（包里常常只有 .env.example，复制一份改名），ThinkPHP 看 config/database.php，裸 PHP 项目一般在 config/ 或 include/ 下的某个 conn 文件里
• Python：Django 在 settings.py 的 DATABASES，Flask / FastAPI 多半在 config.py 或 .env
• Node.js：根目录的 .env，或 config/ 下按环境分的那几个文件
• Go：config.yaml / config.toml 一类，少数直接写在 main.go 里
• .NET 老项目（.NET Framework）：改 Web.config 的 <connectionStrings> 节点
• .NET 新项目（ASP.NET Core）：改 appsettings.json 里的 ConnectionStrings

SQL Server 连接串常见写法：Server=localhost;Database=库名;User Id=sa;Password=你的密码;TrustServerCertificate=True;

找不到配置文件时有个通用办法：在整个项目里搜数据库主机名（localhost、127.0.0.1）或作者机器上的用户名，连接串基本都在搜出来的那几行里。

提示：.NET 项目用的新版 Microsoft.Data.SqlClient 默认要求加密连接，本机开发连不上时补一个 TrustServerCertificate=True 往往就好了。数据库本身怎么装、怎么把项目自带的库导进去，见「数据库如何安装」。

二、依赖装不上、或者不知道从哪个命令启动

A：源码包为了减小体积，一律不带依赖目录（node_modules、vendor、packages、虚拟环境），要按项目用的技术栈自己还原一次。根目录那个依赖清单文件就是答案：

• 有 pom.xml（Java / Maven）：mvn clean package 编译，Spring Boot 项目 mvn spring-boot:run 直接跑
• 有 build.gradle（Java / Gradle）：./gradlew bootRun（Windows 用 gradlew.bat bootRun）
• 有 composer.json（PHP）：composer install；Laravel 再走一次 php artisan key:generate，然后 php artisan serve
• 有 requirements.txt（Python）：先建虚拟环境 python -m venv .venv 并激活，再 pip install -r requirements.txt；Django 项目用 python manage.py runserver 启动
• 有 package.json（Node.js / 前端）：看同目录下的锁文件决定用哪个包管理器——package-lock.json 用 npm install、yarn.lock 用 yarn、pnpm-lock.yaml 用 pnpm install。启动命令不要猜，打开 package.json 看 scripts 那一节，常见的是 npm run dev 或 npm start
• 有 go.mod（Go）：go mod download 之后 go run .
• 有 .sln / .csproj（.NET）：dotnet restore 之后 dotnet run，老项目见第八条

装不上多半是网络问题，不是项目坏了。这几个包管理器默认都从境外源拉，卡住或超时先换国内镜像：npm 用 npm config set registry https://registry.npmmirror.com，pip 加 -i https://pypi.tuna.tsinghua.edu.cn/simple，Maven 在 settings.xml 里配阿里云 mirror，composer 用 composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/，Go 设 GOPROXY=https://goproxy.cn,direct。

另外看一眼项目里有没有 README / Dockerfile / docker-compose.yml——作者把启动方式写在那儿的情况很多，有 compose 文件时一句 docker compose up 往往连数据库一起起好了。

三、空引用 / 空指针（NullReferenceException、NullPointerException、undefined）

A：某个对象是空的就直接用了，各语言叫法不同（C# 是 NullReferenceException、Java 是 NullPointerException、JS 是 undefined / null），常见来源都一样：

1. 数据库里没有对应数据，查询返回 null（最常见——很多源码包自带的库是空库）
2. 配置项没读到（配置文件或 .env 里少了某个键）
3. 会话（Session）已过期或未赋值
4. 页面上的元素或字段名与后台代码对不上
5. 对象声明后没有 new 就使用

排查办法：在异常堆栈指向的那一行打断点，看清楚到底哪个变量是 null，不要凭猜。

四、本地运行提示端口被占用

A：改端口即可，各技术栈改的地方不同：

• ASP.NET Core：Properties/launchSettings.json 里的 applicationUrl，或运行时指定 dotnet run --urls "http://localhost:5080"
• Spring Boot：application.yml 里的 server.port
• Node.js：多数项目读环境变量 PORT，也可以在 .env 里改
• Django：python manage.py runserver 8001

想知道端口被谁占了：Windows 上 netstat -ano | findstr :端口 再按 PID 到任务管理器里找，Linux / macOS 上 lsof -i :端口。

五、页面能打开但样式、图片全丢

A：多为静态资源路径问题：

1. 项目部署在子目录下，而页面里写的是绝对路径 /css/site.css，改成相对路径或配置好虚拟目录
2. 静态文件要放在框架约定的目录里才会被托管：Spring Boot 是 src/main/resources/static，Django 要先 collectstatic，ASP.NET Core 是 wwwroot；前后端分离的项目要先 npm run build 生成前端产物
3. 原作者引用了已失效的外部 CDN，换成本地文件即可

六、本机能访问，别的机器访问不了

A：按这个顺序查：

1. 监听地址：只监听 localhost 时外部访问不到，改成 http://0.0.0.0:端口
2. 防火墙：Windows 防火墙放行对应端口
3. 云服务器：安全组 / 入方向规则要放行该端口

七、Java / PHP / Python / Node.js 的高频报错

• Java：Unsupported class file major version / 编译报语法错——JDK 版本对不上。看 pom.xml 里的 maven.compiler.source 或 java.version，装上那个版本（多个版本并存时用 JAVA_HOME 切）。Spring Boot 项目默认占 8080 端口，冲突时在 application.yml 里改 server.port
• PHP：页面一片空白——多半是致命错误而显示被关了。把 php.ini 里的 display_errors 打开，或直接看 PHP / Apache 的 error_log。提示某个函数不存在（call to undefined function）时是扩展没开，在 php.ini 里取消对应 extension= 那行的注释再重启
• Python：pip install 卡在编译——某个包要本机编译，Windows 上装「Visual Studio 生成工具（C++）」，或者换一个带预编译包的 Python 版本。ModuleNotFoundError 则通常是虚拟环境没激活，装到了另一个解释器里
• Node.js：装依赖或启动时报语法错——Node 版本太低或太高。用 nvm 装上项目要求的版本（看 package.json 的 engines 或 .nvmrc）。node-sass 一类的老依赖对 Node 版本很挑，报错里会直接写出它支持到哪一版
• 都会遇到的：换行符和编码。在 Windows 上打开的脚本传到 Linux 上跑，报 bad interpreter 是换行符问题；中文乱码则统一存成 UTF-8

八、.NET 项目的专有问题

站上存量项目里 .NET 不少，下面几条只对 .NET 项目适用。

还原 / 编译时报缺少程序集、找不到 NuGet 包

A：源码包为了减小体积通常不带 packages / bin 目录，需要自己还原依赖：

• 命令行在解决方案目录执行 dotnet restore（老项目在 Visual Studio 里右键解决方案 →「还原 NuGet 包」）
• 还原失败多半是网络问题，可以换用国内镜像源
• 老项目若引用了本地 dll，检查源码包里的 lib / Bin 目录是否完整，引用路径是否还指向作者机器上的绝对路径

提示目标框架不匹配 / 打不开

A：看项目详情页「项目参数」标注的框架版本，再对照本机装的 SDK：

• ASP.NET Core 项目：装对应版本或更高版本的 .NET SDK；若项目指定 net6.0 而本机只有 .NET 10，可在 csproj 里把 TargetFramework 改成 net10.0 试跑，多数项目能直接编译
• .NET Framework 项目：需要 Windows + 对应版本的开发包；指定 2.0/3.5 的老项目，要在「启用或关闭 Windows 功能」里勾选 .NET Framework 3.5
• 项目文件格式太老时，用 Visual Studio 打开会提示升级，按提示升级即可

ASP.NET Core 项目部署到 IIS 报 500.19 / 500.30 / 502.5

A：这是部署 ASP.NET Core 最高频的三个错误：

• 500.19：服务器没装 ASP.NET Core Hosting Bundle（托管捆绑包），装完执行 iisreset
• 500.30 / 502.5：应用启动阶段就崩了，通常是连接字符串、必需的环境变量没配。到 IIS 站点目录的 logs 文件夹或事件查看器看具体异常
• 应用程序池的「.NET CLR 版本」应选「无托管代码」（ASP.NET Core 不走 CLR 托管管道）

老项目里的组件在新环境下用不了

A：早年的项目可能依赖已停止维护的组件（ASP.NET AJAX、Silverlight、某些收费控件、32 位 COM 组件等）。这类项目建议：

1. 优先在与项目同期的环境里运行（.NET Framework 4.8.1 + IIS 通常都能跑）
2. 只是学习用途的话，重点看业务逻辑与数据库设计，界面层可以用 ASP.NET Core 重写
3. 涉及 32 位组件时，把 IIS 应用程序池的「启用 32 位应用程序」设为 True

还是解决不了？

可以在项目详情页留言向作者提问，或联系客服（电话：4008-010-151）。若项目存在明显缺失或无法运行，见「下载的项目有问题？」。