Windows Server子目录部署Laravel项目出现404 Not Found错误的原因及解决方法咨询

我之前帮不少开发者解决过Windows Server子目录部署Laravel时的404问题，总结下来主要有以下几个常见原因，还有对应的完整部署步骤，你可以一步步排查和操作：

一、可能导致404错误的原因 #

• URL重写规则未正确配置：Laravel依赖URL重写将所有请求导向public/index.php，如果子目录下的web.config规则路径错误，或者IIS未启用URL Rewrite模块，就会导致请求无法被正确转发。
• 子目录权限不足：Laravel的storage、bootstrap/cache目录需要读写权限，如果IIS应用池的身份（比如IIS_IUSRS或自定义应用池账户）没有这些目录的读写权限，会导致路由无法正常加载，进而返回404。
• .env配置错误：.env文件中的APP_URL未设置为包含子目录的完整路径（比如http://your-domain.com/laravel-sub），会导致路由生成和请求解析出现偏差。
• 未将public目录设为应用根目录：很多人会把整个Laravel项目直接放在子目录，但没有将IIS应用程序的物理路径指向项目的public文件夹，导致请求无法进入Laravel的入口文件。
• 路由缓存问题：如果之前运行过php artisan route:cache，但部署后没有重新生成路由缓存，新的路由无法被识别，也会出现404。

二、Windows Server子目录部署Laravel的正确步骤 #

1. 先安装必要的IIS组件 #

确保IIS已经安装了URL Rewrite模块（可以通过IIS管理器的“模块”功能查看，没有的话需要从微软官网下载安装），这个模块是Laravel URL重写的核心依赖。

2. 上传并配置项目文件 #

• 将Laravel项目上传到Windows Server的子目录，比如C:\inetpub\wwwroot\laravel-sub。
• 在IIS管理器中，找到你的主网站，右键点击添加虚拟目录，别名设为你的子目录名称（比如laravel-sub），物理路径选择项目的public文件夹（比如C:\inetpub\wwwroot\laravel-sub\public）。
• 右键点击刚创建的虚拟目录，选择“转换为应用程序”，关联到合适的应用池（建议使用.NET CLR版本为“无托管代码”的应用池，因为Laravel是PHP项目）。

3. 配置web.config文件 #

在项目的public目录下创建或修改web.config文件，确保重写规则适配子目录，示例内容如下：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="Laravel Subdirectory" stopProcessing="true">
                    <match url="^(.*)$" ignoreCase="false" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
                        <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
                    </conditions>
                    <action type="Rewrite" url="/laravel-sub/index.php/{R:1}" />
                </rule>
            </rules>
        </rewrite>
        <defaultDocument>
            <files>
                <add value="index.php" />
            </files>
        </defaultDocument>
    </system.webServer>
</configuration>

注意：把/laravel-sub/替换成你实际的子目录名称。

4. 配置.env文件 #

打开项目根目录的.env文件，修改以下配置：

APP_URL=http://your-domain.com/laravel-sub
APP_DEBUG=false # 调试完成后建议关闭

确保APP_URL包含完整的子目录路径。

5. 设置目录权限 #

• 找到项目的storage和bootstrap/cache目录，右键选择“属性”→“安全”。
• 添加IIS_IUSRS和当前应用池的身份账户（比如IIS AppPool\YourAppPoolName），并赋予它们读取和写入权限。

6. 清除缓存 #

在项目根目录打开命令提示符（或PowerShell），运行以下命令清除缓存：

php artisan config:cache
php artisan route:cache
php artisan view:cache

如果无法直接运行命令，也可以手动删除bootstrap/cache目录下的所有文件。

完成以上步骤后，重新访问子目录的Laravel项目，应该就能正常加载，不会再出现404错误了。

内容的提问来源于stack exchange，提问作者Ali Aljarrah