.NET MVC替换Bootstrap3为Bootstrap5后jQuery报$未定义错误

• 已查阅Stack Overflow多个同主题问题，未找到匹配当前故障的解决方案
• 基于.NET Framework新建MVC解决方案，计划移除内置的Bootstrap 3.x版本替换为Bootstrap 5.x，通过替换对应静态文件、修改BundleConfig中的Bootstrap脚本与CSS绑定配置完成替换

原有绑定配置 #

bundles.Add(new ScriptBundle("~/bundles/bootstrap").Include(
                  "~/Scripts/bootstrap.js"));

bundles.Add(new ScriptBundle("~/Content/css").Include(
                  "~/Content/bootstrap.css",
                  "~/Content/site.css"));

修改后的绑定配置 #

bundles.Add(new Bundle("~/bundles/bootstrap").Include(
                  "~/Scripts/bootstrap.js"));

bundles.Add(new Bundle("~/Content/css").Include(
                  "~/Content/bootstrap.css",
                  "~/Content/site.css"));

故障现象 #

• 替换完成后Bootstrap 5运行完全正常，但jQuery无法工作
• 根据Bootstrap官方说明：Bootstrap 5不再依赖jQuery，但会自动检测页面加载的jQuery并完成适配保证正常渲染
• 在Index.cshtml页面编写如下简单jQuery测试代码时，浏览器控制台抛出错误：Uncaught ReferenceError: $ is not defined

$(document).ready(function() {
console.log("ready!");
});

完整BundleConfig配置 #

public class BundleConfig
{
    // For more information on bundling, visit https://go.microsoft.com/fwlink/?LinkId=301862
    public static void RegisterBundles(BundleCollection bundles)
    {
        bundles.Add(new ScriptBundle("~/bundles/jquery").Include(
                    "~/Scripts/jquery-{version}.js"));

        bundles.Add(new ScriptBundle("~/bundles/jqueryval").Include(
                    "~/Scripts/jquery.validate*"));

        // Use the development version of Modernizr to develop with and learn from. Then, when you're
        // ready for production, use the build tool at https://modernizr.com to pick only the tests you need.
        bundles.Add(new ScriptBundle("~/bundles/modernizr").Include(
                    "~/Scripts/modernizr-*"));

        bundles.Add(new Bundle("~/bundles/bootstrap").Include(
                  "~/Scripts/bootstrap.js"));

        bundles.Add(new Bundle("~/Content/css").Include(
                  "~/Content/bootstrap.css",
                  "~/Content/site.css"));
    }
}

完整Layout.cshtml布局页代码 #

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Great Lakes Bible Church</title>
    @Styles.Render("~/Content/css")
    @Scripts.Render("~/bundles/modernizr")
    <script src="https://kit.fontawesome.com/341cefdc07.js" crossorigin="anonymous"></script>
</head>
<body>
    <div class="navigation-section">
        <nav class="navbar navbar-expand-lg navbar-light">
            <div class="container-fluid">
                <a>
                    @Html.ActionLink("Great Lakes Bible Church", "Index", "Home", new { area = "" }, new { @class = "navbar-brand" })
                </a>
                <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#NavItems" aria-controls="NavItems" aria-expanded="false" aria-label="Toggle navigation">
                    <span class="navbar-toggler-icon"></span>
                </button>
                <div class="collapse navbar-collapse" id="NavItems">
                    <ul class="navbar-nav ms-md-auto">
                        <li>
                            <a>
                                @Html.ActionLink("What We Believe", "WhatWeBelieve", "Home", new { area = "" }, new { @class = "nav-link" })
                            </a>
                        </li>
                        <li>
                            <a>
                                @Html.ActionLink("Map & Directions", "MapAndDirections", "Home", new { area = "" }, new { @class = "nav-link" })
                            </a>
                        </li>
                        <li>
                            <a>
                                @Html.ActionLink("Ministries", "Ministries", "Home", new { area = "" }, new { @class = "nav-link" })
                            </a>
                        </li>
                        <li>
                            <a>
                                @Html.ActionLink("Sermons and Notes", "SermonsAndNotes", "Home", new { area = "" }, new { @class = "nav-link" })
                            </a>
                        </li>
                        <li>
                            <a>
                                @Html.ActionLink("Meet Our Team", "MeetOutTeam", "Home", new { area = "" }, new { @class = "nav-link" })
                            </a>
                        </li>
                        <li>
                            <a>
                                @Html.ActionLink("Connect With Us", "ConnectWithUs", "Home", new { area = "" }, new { @class = "nav-link" })
                            </a>
                        </li>
                        <li>
                            <a>
                                @Html.ActionLink("Give Online", "GiveOnline", "Home", new { area = "" }, new { @class = "nav-link" })
                            </a>
                        </li>
                    </ul>
                </div>
            </div>
        </nav>
    </div>
    <div class="container body-content">
        @RenderBody()
        <hr />
        <footer>
            <a href="https://www.facebook.com/Great-Lakes-Bible-Church-565718963772258/?ref=page_internal"><span class="fa-brands fa-facebook-f footer-icon"></span></a>
            <a><span class="fa-brands fa-instagram footer-icon"></span></a>
            <a><span class="fa-solid fa-envelope footer-icon"></span></a>
            <p>&copy; Copywrite @DateTime.Now.Year Great Lakes Bible Church</p>
        </footer>
    </div>

    @Scripts.Render("~/bundles/jquery")
    @Scripts.Render("~/bundles/bootstrap")
    @RenderSection("scripts", required: false)
</body>
</html>

附加参考材料 #

• 已提供项目Scripts目录下JS脚本列表截图
• 已提供项目中Bootstrap相关文件列表截图

故障原因与修复方案 #

核心问题是jQuery代码执行时机早于jQuery库加载：

• 布局页中jQuery脚本被放在页面底部</body>标签前渲染，@RenderBody()输出的视图内容会在jQuery加载前就被解析执行，此时$变量还未定义，直接写在视图顶层的jQuery代码必然报错。
• 布局页预留的scripts节点是在jQuery、Bootstrap脚本全部加载完成后才会渲染的，所有依赖jQuery的自定义代码都需要放到这个节点内。

修复方式：将Index.cshtml中的测试代码包裹在scripts Section中即可：

@section scripts {
    <script>
        $(document).ready(function() {
            console.log("ready!");
        });
    </script>
}

额外校验点：

• 确认Scripts目录下的jQuery文件命名符合jquery-{version}.js的通配规则（例如jquery-3.7.1.js），如果文件名不匹配，jQuery绑定不会输出脚本引用，同样会触发$ is not defined错误。
• 你将Bootstrap脚本、CSS的绑定从ScriptBundle/StyleBundle替换为基础Bundle的操作是正确的：旧版System.Web.Optimization自带的JS/CSS压缩器不兼容Bootstrap 5的语法，使用基础Bundle可以避免自动压缩导致的Bootstrap运行异常。

内容的提问来源于stack exchange，提问作者Matthew Baier