新增图片后Cloudflare Pages部署构建失败求助

问题背景 #

基于React、TypeScript和Webpack的应用部署在Cloudflare Pages，添加新图片FactionWar.png后部署失败，提示找不到该文件，但本地运行、构建均正常，旧图片无问题。错误行号与本地版本不匹配，尝试更新依赖、重启构建任务无效。

详细错误信息 #

11:55:11.822    ERROR in ./src/app/pages/Projets.tsx 13:0-55
11:55:11.822    Module not found: Error: Can't resolve '../deps/images/FactionWar.png' in '/opt/buildhome/repo/src/app/pages'
11:55:11.822    resolve '../deps/images/FactionWar.png' in '/opt/buildhome/repo/src/app/pages'
11:55:11.822      using description file: /opt/buildhome/repo/package.json (relative path: ./src/app/pages)
11:55:11.822        Field 'browser' doesn't contain a valid alias configuration
11:55:11.822        using description file: /opt/buildhome/repo/package.json (relative path: ./src/app/deps/images/FactionWar.png)
11:55:11.822          no extension
11:55:11.822            Field 'browser' doesn't contain a valid alias configuration
11:55:11.823            /opt/buildhome/repo/src/app/deps/images/FactionWar.png doesn't exist
11:55:11.823          .tsx
11:55:11.823            Field 'browser' doesn't contain a valid alias configuration
11:55:11.823            /opt/buildhome/repo/src/app/deps/images/FactionWar.png.tsx doesn't exist
11:55:11.823          .ts
11:55:11.823            Field 'browser' doesn't contain a valid alias configuration
11:55:11.823            /opt/buildhome/repo/src/app/deps/images/FactionWar.png.ts doesn't exist
11:55:11.823          .js
11:55:11.823            Field 'browser' doesn't contain a valid alias configuration
11:55:11.823            /opt/buildhome/repo/src/app/deps/images/FactionWar.png.js doesn't exist
11:55:11.824          as directory
11:55:11.824            /opt/buildhome/repo/src/app/deps/images/FactionWar.png doesn't exist
11:55:11.824     @ ./src/app/core/Core.tsx 16:0-43 32:303-310
11:55:11.824     @ ./src/app/core/Application.tsx 3:0-30 52:34-38
11:55:11.824     @ ./src/index.ts 1:0-53 2:14-25
11:55:11.824    
11:55:11.824    webpack 5.89.0 compiled with 1 error in 11339 ms
11:55:11.882    Failed: Error while executing user command. Exited with error code: 1
11:55:11.893    Failed: build command exited with code: 1
11:55:13.090    Failed: error occurred while running build command

相关代码片段 #

导入语句 #

import React, {ReactElement} from "react";
import Particles from "@tsparticles/react";
import {APP_NAME} from "../constants/Global"
import Container from "react-bootstrap/Container";
import {Application} from "../core/Application";
import {ProjectCard} from "../components/ProjectCard";
import TMAcceuil from "../deps/images/TaskMasterAccueil.png";
import InfiniteCraft from "../deps/images/InfiniteCraft.png";
import Revolvair from "../deps/images/Revolvair.jpg";
import SimulationGame from "../deps/images/SimulationGame.png";
import GardienLegend from "../deps/images/GardienLegend.png";
import FactionWar from "../deps/images/FactionWar.png";
import WIP from "../deps/images/WIP.png";
import {ParticlesOptsDark} from "../types/ParticlesDark";
import {ParticlesOpts} from "../types/Particles";
import {Row} from "react-bootstrap";

Webpack配置 #

import path from "path";
import HtmlWebpackPlugin from "html-webpack-plugin";
import {fileURLToPath} from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default {
    performance: {
        hints: false,
        maxEntrypointSize: 512000,
        maxAssetSize: 512000
    },
    devtool: false,
    output: {
        path: path.join(__dirname, "build"),
        filename: "[name].bundle.js",
        publicPath: "/"
    },
    mode: process.env.NODE_ENV || "development",
    resolve: {
        extensions: [".tsx", ".ts", ".js"],
        fallback: {
            "fs": false,
            "tls": false,
            "net": false,
            "path": false,
            "zlib": false,
            "http": false,
            "https": false,
            "stream": false,
            "crypto": false
        }
    },
    module: {
        unknownContextCritical: false,
        rules: [
            {
                test: /\.(js|jsx)$/,
                exclude: /node_modules/,
                use: ["babel-loader"],
            },
            {
                test: /\.(ts|tsx)$/,
                exclude: /node_modules/,
                use: ["ts-loader"],
            },
            {
                test: /\.(css|scss)$/,
                use: ["style-loader", "css-loader"],
            },
            {
                test: /\.(png|jpe?g|gif|jp2|webp|svg)$/,
                loader: 'file-loader',
                options: {
                    name: 'images/[name].[ext]'
                }
            }
        ],
    },
    devServer: {
        historyApiFallback: true,
        static: path.join(__dirname, "src")
    },
    optimization: {
        runtimeChunk: 'single',
    },
    plugins: [
        new HtmlWebpackPlugin({
            template: path.join(__dirname, "src/html", "index.html"),
            favicon: "./src/html/favicon.ico",
        })
    ]
};

TypeScript图片声明文件（src/app/import-img.d.ts） #

declare module "*.png" {
    const value: never;
    export default value;
}
declare module "*.jpg" {
    const value: never;
    export default value;
}
declare module "*.jpeg" {
    const value: never;
    export default value;
}

declare module "*.svg" {
    const value: never;
    export default value;
}

解决方案 #

1. 确认新图片已提交到Git仓库 #

• 本地执行git status，检查FactionWar.png是否处于未追踪状态。如果是，执行：

  git add src/app/deps/images/FactionWar.png
  git commit -m "Add FactionWar.png"
  git push
  

• 检查文件名大小写：Cloudflare构建环境基于Linux，严格区分大小写。如果本地是Windows/macOS（默认不区分大小写），确保导入路径的文件名和实际文件完全一致（比如不要出现本地是factionwar.png但导入写FactionWar.png的情况）。

2. 修正TypeScript图片声明文件 #

将import-img.d.ts中图片模块的value类型从never改为string，因为Webpack处理图片后会返回文件路径字符串：

declare module "*.png" {
    const value: string;
    export default value;
}
declare module "*.jpg" {
    const value: string;
    export default value;
}
declare module "*.jpeg" {
    const value: string;
    export default value;
}

declare module "*.svg" {
    const value: string;
    export default value;
}

同时确保tsconfig.json的include数组包含该文件，比如：

{
  "include": ["src/**/*"]
}

3. 适配Webpack 5的资源处理 #

Webpack 5已内置资源模块，无需再使用file-loader，替换图片处理规则：

{
    test: /\.(png|jpe?g|gif|jp2|webp|svg)$/,
    type: 'asset/resource',
    generator: {
        filename: 'images/[name].[ext]'
    }
}

然后卸载file-loader：

npm uninstall file-loader

4. 解决行号不匹配问题 #

• 确认本地所有修改都已提交并推送到远程仓库，Cloudflare Pages拉取的是正确的分支。
• 检查Cloudflare Pages的构建配置，确保构建命令和本地一致，没有使用缓存的旧代码。

内容的提问来源于stack exchange，提问作者William Blanchet Lafrenièr