wordpress-基于_s主题开发配置

by zhuzhenPosted on

常规配置直接根据readme文件即可，如批量修改名称等。对于遇到的坑点和知识盲区，笔记备忘。

◆ Node.js手动安装

如：我所下载的是【 node-v22.14.0-win-x64.zip 】文件，直接解压即可，但是需要自行手动安装并配置环境变量。

2：自行创建全局目录：【node_global】：用于存放全局安装的 npm 包。【node_cache】：用于存放 npm 缓存文件。

◆ Node.js中npm安装速度慢

切换国内镜像源

npm config set registry https://registry.npmmirror.com  # 切换到国内镜像源

◆ nodejs环境变量路径配置正确，但是其他目录下解析不了node命令

echo %PATH%

执行命令【echo %PATH%】路径，查看noedjs路径是否和【高级 → 环境变量】配置一致，我就是出现两者不一致，导致运行不了 node 或 npm 命令，重新配置即可。

◆ Node.js在VS Code 的终端无法执行命令

错误提示：npm : 无法加载文件 C:\soft\nodejs\node-v22.14.0-win-x64\npm.ps1。

原因：本人的VS Code 【默认】终端是 【PowerShell 】（非系统 CMD），所以检查VS Code 终端当前是否使用【 PowerShell】，由于【 PowerShell】运行nodejs命令权限限制较多，而我nodejs又是直接解压配置，所以【 PowerShell】会禁止运行未签名的 PowerShell 脚本。

解决：VS Code 【默认】终端设置为【系统 CMD】。

◆ Node.js工具node-sass替换为dart-sass

SASS 是 CSS 的预处理语言：它通过变量、嵌套、混合等语法增强了 CSS 的灵活性，但浏览器无法【直接解析 】SASS 文件。所以需要Node.js工具【node-sass】，把所有 SASS 代码最终都需要被编译成浏览器能理解的原生 CSS，才能生效。而且Node.js工具【node-sass】运行命令【npm run watch】，可以实现监听 SASS 文件变化并自动编译为 CSS。

我所下载的【_s主题】，在GitHub好几年没有维护更新了【截至2525-03-30】。而我用的是node版本是较新的【 node-v22.14.0】，而旧版本的 node-sass 可能不兼容 Node.js 22.x。颇为麻烦，而且【node-sass】依赖于【python】，又要配置【python】，颇为头疼。为了解决这个问题，走了一下午的弯路，包括配置python，重装就版本node，切换npm镜像源等，最后还是不行。查询相关资料可知，【node-sass】都快要被弃用了，现在是【dart-sass】大行其道，wordpress官方推荐用它，所以我索性也不用了，直接替换【dart-sass】。

【dart-sass】直接通过 Dart 语言实现，避免 node-gyp 和 Python 依赖。兼容性优于 node-sass，关键是安装简单，彻底解决证书、路径、版本匹配等问题。

npm install sass --save-dev

原因：本人的VS Code 【默认】终端是 【PowerShell 】（非系统 CMD），所以检查VS Code 终端当前是否使用【 PowerShell】，由于【 PowerShell】运行nodejs命令权限限制较多，而我nodejs又是直接解压配置，所以【 PowerShell】会禁止运行未签名的 PowerShell 脚本。

解决：VS Code 【默认】终端设置为【系统 CMD】。

◆ 为什么需要Composer

PHP 依赖管理：用于安装 PHP 代码检查工具（如 wp-coding-standards）。

echo %PATH%

◆ Composer手工安装

1：访问 Composer 官方网站，下载Composer 的【 phar 文件】，phar是 PHP Archive 的缩写，是 PHP 特有的打包格式，直接运行即可使用，无需安装程序。

2：创建目目录（如C:\soft\php\Composer\bin），并将【composer.phar】移动到该目录。

3：配置环境变量。目录路径（即 C:\soft\php\Composer\bin）

4：创建批处理文件【composer.bat】，其目的是能够在【非安装目录】也能运行composer命令。脚本如下：

@php "%~dp0composer.phar" %*

5：测试composer命令：php composer.phar –version

php composer.phar --version

◆ npm install安装相关工具包

前面说到，我是较新的nodejs版本。所以干脆nodejs相关工具全都无脑安装最新版本得了。有问题再慢慢排查。

package.json文件【devDependencies】配置如下：

  "devDependencies": {
    "@wordpress/scripts": "^19.2.2",
    "dir-archiver": "^1.1.1",
    "node-sass": "^7.0.1",
    "rtlcss": "^3.5.0"
  },

版本太低了，全都删了，安装最新版本，最后如下：

  "devDependencies": {
    "@wordpress/scripts": "^30.14.0",
    "dir-archiver": "^2.1.0",
    "rtlcss": "^4.3.0",
    "sass": "^1.86.0"
  }
  "scripts": {
    "watch": "sass --watch sass/:./ --source-map --style=expanded",
    "compile:css": "sass sass/:./ && stylelint '*.css' --fix || true && stylelint '*.css' --fix",
    "compile:rtl": "rtlcss style.css style-rtl.css",
    "lint:scss": "wp-scripts lint-style 'sass/**/*.scss'",
    "lint:js": "wp-scripts lint-js 'js/*.js'",
    "bundle": "dir-archiver --src . --dest ../_s.zip --exclude .DS_Store .stylelintrc.json .eslintrc .git .gitattributes .github .gitignore README.md composer.json composer.lock node_modules vendor package-lock.json package.json .travis.yml phpcs.xml.dist sass style.css.map yarn.lock"
  }

注意，我把【”node-sass”】也换成了【”sass”】，相关sass执行脚本【”scripts”】也要修改。

◆ 禁止生成 CSS Source Map 文件

有时候修改scss代码，刷新浏览器后一直不生效，估计是缓存问题，删除掉map文件，直接用编译后的css文件就正常，但是每次调试时，清理浏览器缓存或者删除map太麻烦了，干脆直接禁止生成 CSS Source Map 文件。json配置如下

  "scripts": {
    "watch": "sass --watch sass/:./  --style=expanded --no-source-map",

◆ 重构Sass目录

从Sass 1.23.0开始，@import逐渐被@use和@forward取代。而[s_]主题里面的scss文件还是用【@import】引用功能，所以也都重构。由于原先【@import】默认全局引入，所有变量和混合在【全局】作用域共享，容易导致命名冲突，直接改为 @forward 或者@use还是有很多问题，慢慢调试修改吧。

以目录【abstracts】为例：

1：每个目录创建 _index.scss 作为聚合入口，【_index.scss】 是目录的入口文件，Sass 会自动识别。把原先 文件【_abstracts.scss】删掉，用 @forward 统一暴露内容。

// abstracts/variables/_index.scss
@forward  "colors";
@forward  "typography";
@forward  "structure";
@forward  "columns";

// abstracts/_index.scss
@forward "variables";
@forward  "mixins";

2：主文件style.scss修改为如下

// style.scss
@use "abstracts" as *;   // 引入所有抽象层变量/混合
@use "base";             // 基础样式
@use "components";       // 组件样式
@use "layouts";          // 布局
@use "plugins";          // 插件
@use "utilities";        // 工具类

3：其他文件引用scss变量：如：sass\base\elements\_body.scss

@use "../../abstracts" as *;
body {
	background: $color__background-body; 
}