Webpack4+Handlebars项目根文件夹含连字符导致运行异常问题咨询

核心结论 #

Webpack、Handlebars本身对路径中的连字符没有限制，此类故障和连字符本身无关，是项目配置中存在路径校验/匹配规则导致的异常，常见原因如下：

常见故障原因 #

• 目录名匹配校验规则异常
  多数此类问题是项目配置中添加了运行根目录名和package.json中name字段的一致性校验。对应样板工程的package.json中name字段值为boilerplate-html，但下载zip包解压后默认的根目录名为boilerplate-html-main，多了-main后缀，匹配失败直接中断流程。将目录改为test后规则未命中校验逻辑，因此可以正常运行。
• Webpack路径解析规则配置错误
  检查webpack.config.js中涉及路径处理的逻辑：
  • 有没有自定义正则用于匹配根目录路径，错误将连字符判定为非法字符
  • 有没有写死的路径alias、上下文（context）配置，和实际运行目录名不匹配
• 加载器或自定义脚本逻辑问题
  • 检查handlebars-loader等模板处理插件的配置，是否设置了错误的根路径过滤规则，将含连字符的目录排除在资源解析范围外
  • 检查npm start、npm run build调用的自定义Node脚本，有没有硬编码的目录名格式校验逻辑，限制只能使用纯字母命名的根目录

排查方案 #

• 执行npm run build -- --stats-error-details 打印详细报错栈，直接定位抛出异常的代码位置
• 移除项目中不必要的根目录名校验逻辑，或修改校验规则允许连字符、后缀等合法目录名字符
• 所有路径处理统一使用path.resolve(__dirname, 'xxx')等相对路径写法，不要硬编码根目录名称

内容的提问来源于stack exchange，提问作者PixelRocket。