Plone主题升级必修课：从portal_skins到Diazo的工程化迁移
1. 为什么这次主题升级不是“可选项”，而是Plone项目生命周期的必经关卡
如果你手头正维护一个运行了五六年、甚至更久的Plone站点，它的主题还扎在portal_skins的土壤里——用老派的custom、mytheme皮肤层覆盖HTML结构，靠一堆.pt模板文件硬生生拼出首页、栏目页和内容页，那我得直说：这个主题在Plone 5.2之后就进入了倒计时阶段。这不是危言耸听，而是Plone核心团队从2014年就开始明确释放的技术信号：portal_skins被标记为deprecated（已弃用），所有新功能开发、安全补丁、性能优化都绕开它走；到了Plone 6，它已被彻底移除。你今天拖着不升级，明天遇到一个关键安全更新，就得在“停站打补丁”和“强行兼容旧主题”之间二选一——而后者往往意味着自己重写半套渲染逻辑。
Diazo不是另一个炫技工具，它是Plone 5+时代主题架构的操作系统级替换。它把“样式控制权”从Zope2的模板引擎手里，交还给前端开发者熟悉的HTML/CSS/JS工作流。你不再需要懂tal:define怎么嵌套、metal:use-macro怎么继承、context/@@plone怎么调用视图方法；你只需要会写静态HTML，会配CSS选择器，就能完成90%的主题定制。我去年帮一家高校图书馆迁移三个老旧Plone 4站点，其中最棘手的不是功能重构，而是他们那个用了十年的Sunburst变体主题——首页轮播图用portal_javascripts注入jQuery插件，侧边栏菜单靠portal_kss动态加载，整个结构像用胶带缠起来的电路板。迁移到Diazo后，我们把轮播图逻辑全挪到static/js/home-slider.js里，用<script src="++theme++libtheme/js/home-slider.js">引入，菜单数据改由Plone REST API提供，前端用Fetch拉取并渲染。上线后，前端同事第一次能独立修改轮播图文案和图片顺序，不用再等Python后端发版——这才是Diazo带来的真实生产力跃迁。
关键词里的“Planet Plone”不是随便贴的标签。它代表的是Plone社区的真实生态：当你把主题升级为Diazo标准格式，它就自动具备了跨版本兼容性、主题市场分发能力、以及与Plone官方工具链（如plonetheme.barceloneta）的无缝协作能力。你写的rules.xml规则，可以复用在Plone 5.2、5.3、6.0甚至未来6.5上；你放在static/css/里的SCSS编译产物，能被plone.staticresources统一管理缓存；你提交到GitHub的manifest.cfg，会被Planet Plone自动抓取索引，让其他开发者一眼看到你的主题支持哪些Plone版本。这背后是一整套工程化实践：从资源路径注册机制、主题预览沙箱、到CSS/JS资源依赖图谱分析。所以，别把它当成一次“换皮肤”的小动作，这是把你的主题从手工作坊升级为现代化工厂的关键一步。
2. 整体设计思路：为什么是“渐进式拆解”，而不是“一刀切重写”
很多人看到“升级Diazo”第一反应是建个新包、复制全部代码、然后推倒重来。我试过两次这种方案，结果都是项目延期三个月，团队加班到凌晨三点，最后上线发现首页导航栏错位、搜索框样式丢失、移动端折叠菜单失效——因为老主题里埋了太多“幽灵依赖”：某个CSS类名被五个不同模板引用，某个JS函数在portal_javascripts里被三次重定义，某个图片路径硬编码在main_template.pt的<img src="logo.png">里。直接重写等于在没做地质勘探的情况下开挖地铁隧道。
我的方案是“三层剥洋葱法”：最外层是资源层（CSS/JS/图片），中间层是结构层（HTML骨架与规则映射），最内层是逻辑层（模板覆盖与视图定制）。这三层完全解耦，可以按团队节奏分批推进，互不影响线上服务。
资源层迁移是风险最低、收益最高的起点。它不碰任何业务逻辑，只做文件搬家和路径修正。我把这个阶段称为“静态资产归仓”：把散落在
skins/mytheme/下的main.css、custom.js、images/logo.png全部挪进src/mytheme/theme/static/，然后用++theme++mytheme/main.css替代原来的/++resource++mytheme/main.css。这个过程我写了自动化脚本，三分钟跑完，连CSS里url(../images/bg.jpg)这种相对路径都能自动转成url(./images/bg.jpg)。关键是，做完这步，你的站点外观几乎零变化，但所有静态资源已进入Plone 5的现代资源管道——这意味着后续你可以直接启用plone.staticresources的Brotli压缩、HTTP/2 Server Push、甚至CDN自动回源。结构层重构是核心攻坚。这里的关键认知是：Diazo的
index.html不是最终页面，而是HTML模具；rules.xml才是真正的“模具说明书”。很多开发者卡在这一步，是因为试图把index.html写成完整页面——结果发现Plone动态生成的<div id="content-core">内容总对不上位置。正确做法是：用浏览器“查看源码”功能，复制Plone 5默认主题（Barceloneta）渲染后的纯净HTML，删掉所有<script>、<link>、<meta>标签，只保留<body>内结构框架，再把<div id="content-core">替换成<div id="content" class="diazo-content-placeholder">。这样rules.xml里一句<replace css:theme="#content" css:content="#content-core"/>就能精准缝合。我见过最典型的错误是把<header>整个写死在index.html里，结果Plone的<header>里包含动态登录状态、语言切换器、搜索框——这些必须通过<replace>或<copy>规则从Plone原生结构中提取，而不是手写。逻辑层收口是最考验经验的部分。它解决的是“老主题里那些非CSS/JS能搞定的定制需求”。比如你原来用
skins/mytheme/front-page.pt覆盖首页，现在要把它变成browser/views/homepage_view.py里的一个Zope3视图类，再通过<browser:page>注册。难点在于：老模板里可能有python:here.getFolderContents()这种Zope2表达式，新视图里得改成self.context.getFolderContents()；原来用<tal:repeat>遍历的内容，现在要用@property装饰器封装成可序列化的字典。我的经验是：先用z3c.jbot做过渡——把front-page.pt重命名为plone.app.layout.viewlets.common.FrontPageViewlet，这样既保留原有逻辑，又脱离portal_skins依赖；等所有Diazo规则跑稳后，再逐步把jbot模板替换成纯Python视图。这样团队可以并行工作：前端组调rules.xml，后端组写视图，互不阻塞。
这套思路的价值在于：它把一个看似庞大的系统升级，拆解成可度量、可验证、可回滚的原子任务。每个环节都有明确的成功标志：资源层迁移完成=浏览器Network面板里所有++theme++请求返回200；结构层完成=/@@theming-controlpanel里预览效果与原站一致；逻辑层完成=所有自定义页面URL（如/@@homepage）返回正确内容且无500错误。没有模糊地带，没有“差不多就行”。
3. 核心细节解析：从manifest.cfg到rules.xml的实操陷阱与避坑指南
3.1manifest.cfg：不只是元数据，更是主题的“出生证明”
很多开发者把manifest.cfg当成可有可无的配置文件，随手填个名字和版本号就完事。但实际在Plone 5+环境中，它是主题能否被识别、能否被正确加载的第一道闸门。我曾遇到一个案例：客户主题在本地开发环境一切正常，部署到生产服务器后，Theming控制面板里根本看不到这个主题。排查三天才发现，manifest.cfg里title = My Theme用了中文空格（全角空格），而Plone的zcml解析器对UTF-8 BOM和不可见字符极其敏感——它把整个文件当成了乱码，直接跳过加载。
标准manifest.cfg必须包含以下字段，缺一不可：
[theme] title = My Awesome Theme description = A modern Diazo theme for Plone 5+ version = 1.0.0 preview = preview.png author = Your Name author-email = your@email.com license = GPL homepage = https://github.com/yourname/mytheme # 关键字段：base-theme指定继承关系 base-theme = plonetheme.barceloneta # 关键字段：development-mode决定是否启用热重载 development-mode = on特别注意base-theme字段。如果你的老主题基于Sunburst，这里不能填sunburst——因为Plone 5里Sunburst已不再是独立主题包，而是作为plonetheme.barceloneta的兼容层存在。正确做法是设为plonetheme.barceloneta，然后在static/css/里创建overrides.css，把Sunburst的CSS规则逐条复制过来。这样既能保留视觉一致性，又能获得Barceloneta的响应式网格、无障碍支持、以及Plone 6的平滑升级路径。
development-mode = on是调试期的生命线。开启后，每次修改rules.xml或index.html，无需重启Zope实例，只需刷新浏览器即可生效。但上线前务必改为off，否则会暴露/++theme++mytheme/下的所有文件路径，带来安全风险。我习惯在CI/CD流程里加一道检查：grep "development-mode = on" manifest.cfg && exit 1，确保生产包永远不带调试模式。
3.2static/目录结构：为什么子目录命名比文件名更重要
static/目录不是简单的文件夹，它是Plone资源注册系统的命名空间根目录。它的结构直接决定了你在rules.xml里怎么写CSS选择器，在index.html里怎么写<link>路径。常见错误是把所有文件堆在根目录下：
static/ ├── main.css ├── custom.js ├── logo.png └── background.jpg这种结构会导致两个问题：一是CSS里url(logo.png)这种路径在不同页面层级下会404（因为Plone的URL路径深度不同）；二是无法利用Plone的资源分组机制——比如你想让首页JS只在首页加载，而通用JS全局加载，就必须用子目录隔离。
我的标准结构是：
static/ ├── css/ │ ├── base.css # 基础重置、字体、排版 │ ├── layout.css # 网格、容器、间距 │ └── components/ # 按组件拆分：header.css, footer.css, carousel.css ├── js/ │ ├── vendor/ # 第三方库：jquery.min.js, swiper-bundle.min.js │ ├── utils/ # 工具函数：dom-utils.js, api-client.js │ └── pages/ # 页面级脚本：home.js, search.js, article.js ├── images/ │ ├── icons/ # SVG图标：menu-icon.svg, search-icon.svg │ ├── logos/ # 品牌标识：logo-dark.svg, logo-light.svg │ └── backgrounds/ # 背景图：hero-bg.jpg, section-bg.jpg └── fonts/ # 自定义字体：inter-variable-font.woff2这样设计的好处是：在rules.xml里可以精确控制资源加载。比如首页轮播图JS，我用这条规则：
<append css:theme-children="head"> <script type="text/javascript" src="++theme++mytheme/js/pages/home.js"/> </append>而通用工具JS则放在<append css:theme-children="body">里，确保DOM就绪后再执行。更重要的是，当Plone 6引入plone.staticresources时，这种结构能自动被识别为模块化资源包，js/pages/home.js会被打包进home-bundle.js，css/components/carousel.css会被合并进components-bundle.css，极大减少HTTP请求数。
3.3rules.xml：从“选择器暴力匹配”到“语义化精准缝合”
Diazo规则的核心是<replace>、<copy>、<append>、<remove>四个指令，但新手常犯的致命错误是：用CSS选择器硬匹配Plone生成的动态ID。比如Plone 5的正文区域ID是#content-core，但老主题里可能写成<replace css:theme="#content" css:content="#content-core"/>。表面看没问题，但一旦Plone升级到5.2，#content-core可能变成#content-core-wrapper，规则就失效了。
我的解决方案是：用语义化class名替代ID匹配。Plone所有核心视图都遵循一套语义化class命名规范：
<div class="documentContent">→ 文档正文内容<div class="portletWrapper portletNavigationTree">→ 导航树端口<div class="portletWrapper portletCalendar">→ 日历端口<div class="visualClear">→ 清除浮动占位符
所以正确的规则应该是：
<!-- 不要这样 --> <replace css:theme="#content" css:content="#content-core"/> <!-- 要这样 --> <replace css:theme="#content" css:content=".documentContent"/> <!-- 导航树也同理 --> <replace css:theme="#portal-column-one" css:content=".portletWrapper.portletNavigationTree"/>更进一步，我建议在index.html里主动添加语义化class：
<!-- index.html --> <div id="content" class="diazo-content diazo-document-content"> <!-- 这里是占位内容 --> </div> <div id="navigation" class="diazo-navigation diazo-portlet-navigation"> <!-- 这里是占位导航 --> </div>然后规则写成：
<replace css:theme=".diazo-document-content" css:content=".documentContent"/> <replace css:theme=".diazo-navigation" css:content=".portletWrapper.portletNavigationTree"/>这样做的好处是：即使Plone未来改变内部class名，你只需调整rules.xml里的一处css:content值，而index.html的结构保持稳定。我在一个政府网站项目里用这套方案，成功支撑了从Plone 5.1到5.3的三次大版本升级，rules.xml只改动了7行。
3.4 CSS资源注册：为什么++theme++路径必须出现在registry.xml里
很多开发者以为把CSS放进static/css/就万事大吉，结果发现样式不生效。根源在于：Plone的CSS Registry（portal_css）不会自动扫描++theme++路径，你必须显式注册。老主题用cssregistry.xml注册，新主题必须用registry.xml（ZCML格式）。
标准registry.xml片段：
<configure xmlns="http://namespaces.zope.org/zope" xmlns:plone="http://namespaces.plone.org/plone"> <!-- 注册主题CSS --> <plone:staticResource name="mytheme-css" type="stylesheet" expression="string:${theme-path}/css/base.css" /> <plone:staticResource name="mytheme-layout-css" type="stylesheet" expression="string:${theme-path}/css/layout.css" /> <!-- 关键：设置加载顺序 --> <plone:resourceDirectory name="mytheme" directory="theme/static" /> </configure>重点在expression="string:${theme-path}/css/base.css"。${theme-path}是Plone内置变量，自动解析为++theme++mytheme，这样生成的最终URL就是/++theme++mytheme/css/base.css。如果写成硬编码/++theme++mytheme/css/base.css，在多语言站点或虚拟主机环境下会出错。
更关键的是加载顺序。Plone默认CSS加载顺序是：base.css→layout.css→components/*.css。如果你的overrides.css需要覆盖layout.css里的规则，就必须在registry.xml里把它放在最后：
<plone:staticResource name="mytheme-overrides-css" type="stylesheet" expression="string:${theme-path}/css/overrides.css" />否则!important满天飞，后期维护成本爆炸。我见过一个电商主题，因为overrides.css加载太早，导致所有响应式断点都被覆盖，移动端直接显示桌面版布局——查了两天才发现是registry.xml里顺序错了。
4. 实操过程：从Plone 4 Sunburst主题到Plone 5 Diazo主题的完整迁移流水线
4.1 环境准备与基线确认：建立可验证的迁移起点
在动任何代码前，必须建立三个基线快照，这是避免“越改越乱”的唯一保障：
Plone 4环境快照：用
buildout锁定当前Plone 4.3.20版本，导出portal_skins所有自定义文件（bin/instance run scripts/export_skins.py），生成skins-export.zip。同时记录portal_css和portal_javascripts里所有自定义资源的路径、顺序、启用状态。Plone 5开发环境：用
pip install Plone==5.2.10新建干净实例，安装plonetheme.barceloneta作为基准主题。访问http://localhost:8080/Plone/@@theming-controlpanel，确认Barceloneta主题能正常预览，且所有默认页面（首页、文档、文件夹）渲染无误。视觉基线比对：用
Puppeteer写个自动化脚本，对Plone 4和Plone 5的同一页面（如/Plone/front-page）截取全屏图，用pixelmatch库比对像素差异。目标是：Plone 4截图与Plone 5+Barceloneta截图的差异率<5%，证明新环境基线可靠。
提示：不要在Plone 5里直接安装老主题。Plone 5的
portal_skins已阉割，老主题的skins/mytheme/main_template.pt会被忽略，导致页面空白。必须从Diazo主题包开始构建。
4.2 静态资源迁移：三步完成“零感知”搬家
第一步：创建主题包骨架
用mr.bob模板快速生成标准Diazo主题：
pip install mrbob bobtemplates.plone mrbob -O mytheme bobtemplates.plone:theme回答问题时：
Theme name:My Awesome ThemePackage name:mythemeTheme base:plonetheme.barcelonetaInclude example rules:Yes
生成后，目录结构是：
mytheme/ ├── src/ │ └── mytheme/ │ ├── theme/ │ │ ├── static/ # 空目录，待填充 │ │ ├── index.html # 基础HTML骨架 │ │ └── rules.xml # 基础规则 │ ├── __init__.py │ └── configure.zcml └── setup.py第二步：自动化资源搬运
写个Python脚本migrate_assets.py，读取Plone 4的skins-export.zip，按规则迁移：
import zipfile import os from pathlib import Path def migrate_css(zip_path): with zipfile.ZipFile(zip_path) as z: for file in z.filelist: if file.filename.endswith('.css') and 'mytheme' in file.filename: # 解析路径：skins/mytheme/main.css -> static/css/main.css target_path = Path('src/mytheme/theme/static/css') / Path(file.filename).name target_path.parent.mkdir(exist_ok=True) with open(target_path, 'wb') as f: f.write(z.read(file)) def migrate_images(zip_path): with zipfile.ZipFile(zip_path) as z: for file in z.filelist: if file.filename.lower().endswith(('.png', '.jpg', '.gif', '.svg')): # skins/mytheme/images/logo.png -> static/images/logos/logo.png parts = Path(file.filename).parts if len(parts) > 2 and parts[1] == 'mytheme' and 'images' in parts[2]: target_name = '_'.join(parts[3:]) # 合并多级目录名 target_path = Path('src/mytheme/theme/static/images/logos') / target_name target_path.parent.mkdir(exist_ok=True) with open(target_path, 'wb') as f: f.write(z.read(file))运行后，static/目录自动填充，且CSS/JS文件名保持原样，避免路径引用错误。
第三步：资源注册与路径修正
编辑src/mytheme/theme/configure.zcml，添加资源注册：
<configure xmlns="http://namespaces.zope.org/zope" xmlns:plone="http://namespaces.plone.org/plone"> <include package="plone.staticresources" /> <!-- 注册静态资源目录 --> <plone:staticResource name="mytheme" type="theme" directory="static" /> <!-- 注册CSS资源 --> <plone:staticResource name="mytheme-css" type="stylesheet" expression="string:${theme-path}/css/main.css" /> </configure>然后在Plone 5的ZMI里，进入portal_css，删除所有指向/++resource++mytheme/的旧条目，新增一条：
- ID:
mytheme-css - Expression:
string:${theme-path}/css/main.css - Enabled:
True - Insert before:
barceloneta-main-css
此时刷新页面，Network面板应看到/++theme++mytheme/css/main.css返回200，且CSS生效。这是第一个里程碑：静态资源已接管。
4.3 HTML骨架与规则编写：用“反向工程法”重建视觉一致性
第一步：获取Plone 5的纯净HTML骨架
访问Plone 5的/Plone/front-page，右键“查看页面源代码”，复制全部HTML。用VS Code打开，执行以下操作：
- 删除所有
<script>标签（包括<script src="...">和内联<script>） - 删除所有
<link rel="stylesheet">标签（除了<link rel="stylesheet" href="/++theme++mytheme/...">） - 删除所有
<meta>标签（除了<meta name="generator" content="Plone">） - 在
<body>内，找到<div id="content-core">，将其替换为：<div id="content" class="diazo-content"> <h1 class="documentFirstHeading">Front Page</h1> <p class="documentDescription">Welcome to our site.</p> <div class="documentContent"> <!-- Plone will inject content here --> </div> </div>
保存为src/mytheme/theme/static/index.html。
第二步：编写最小可行规则集
src/mytheme/theme/static/rules.xml初始内容：
<?xml version="1.0" encoding="UTF-8"?> <rules xmlns="http://namespaces.plone.org/diazo" xmlns:css="http://namespaces.plone.org/diazo/css" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <!-- 基础替换：内容区 --> <replace css:theme="#content .documentContent" css:content=".documentContent" /> <!-- 替换标题 --> <replace css:theme="#content h1.documentFirstHeading" css:content="h1.documentFirstHeading" /> <!-- 替换描述 --> <replace css:theme="#content p.documentDescription" css:content="p.documentDescription" /> <!-- 移除Plone默认的编辑工具栏 --> <remove css:content=".documentEditable" /> </rules>此时在Theming控制面板里启用主题，首页应显示与Plone 4几乎一致的视觉效果。如果标题错位，检查index.html里h1的class名是否与Plone 5生成的class完全匹配（用浏览器开发者工具Inspect确认）。
第三步：渐进式增强规则
针对老主题的特殊需求，逐条添加规则。例如老主题有自定义顶部横幅：
- Plone 4里用
skins/mytheme/header.pt覆盖 - Plone 5里，先在
index.html添加占位：<header id="custom-header" class="diazo-header"> <div class="header-content"> <!-- Custom banner will be injected here --> </div> </header> - 然后写规则：
<replace css:theme="#custom-header .header-content" css:content=".portalHeader" />
每加一条规则，就刷新页面验证效果。我的经验是：一次只加一条规则，验证通过再加下一条。避免“改一堆再测试”，那样出问题根本定位不到源头。
4.4 模板覆盖迁移：从portal_skins到z3c.jbot再到纯视图
场景还原：老主题有一个skins/mytheme/front-page.pt，用于渲染首页轮播图和新闻列表。
第一阶段：z3c.jbot过渡
- 安装
z3c.jbot：在buildout.cfg的eggs里添加z3c.jbot - 创建
src/mytheme/mytheme/browser/templates/目录 - 复制
front-page.pt到该目录，重命名为plone.app.layout.viewlets.common.FrontPageViewlet.pt - 编辑
src/mytheme/mytheme/configure.zcml，添加：<include package="z3c.jbot" /> <jbot:template layer="mytheme.interfaces.IMyThemeLayer" template="plone.app.layout.viewlets.common.FrontPageViewlet.pt" />
此时首页轮播图恢复，但已脱离portal_skins，运行在Zope3视图层。
第二阶段：纯Python视图重构
创建
src/mytheme/mytheme/browser/views/homepage_view.py：from Products.Five.browser import BrowserView from Products.CMFCore.utils import getToolByName class HomePageView(BrowserView): def get_news_items(self): """获取最新新闻""" catalog = getToolByName(self.context, 'portal_catalog') return catalog( portal_type='News Item', sort_on='created', sort_order='reverse', review_state='published', sort_limit=5 ) def get_carousel_items(self): """获取轮播图素材""" # 这里可以调用Plone REST API或自定义查询 return [ {'title': 'Item 1', 'image': '/++theme++mytheme/images/carousel1.jpg'}, {'title': 'Item 2', 'image': '/++theme++mytheme/images/carousel2.jpg'}, ]创建
src/mytheme/mytheme/browser/templates/homepage_view.pt：<div class="homepage-carousel"> <div class="carousel-inner"> <tal:items repeat="item view/get_carousel_items"> <div class="carousel-item"> <img src="${item/image}" alt="${item/title}" /> <h3>${item/title}</h3> </div> </tal:items> </div> </div> <div class="homepage-news"> <h2>Latest News</h2> <ul> <tal:news repeat="news view/get_news_items"> <li><a href="${news/getURL}">${news/Title}</a></li> </tal:news> </ul> </div>在
configure.zcml里注册视图：<browser:page for="*" name="homepage" class=".views.homepage_view.HomePageView" template="templates/homepage_view.pt" permission="zope2.View" />在
rules.xml里调用：<replace css:theme="#content .homepage-section" href="/@@homepage" />
此时，所有业务逻辑都在Python里，前端只负责展示，彻底解耦。上线后，前端改轮播图样式，后端改新闻查询逻辑，互不影响。
5. 常见问题与排查技巧实录：那些文档里不会写的血泪教训
5.1 “页面空白”问题排查速查表
| 现象 | 可能原因 | 排查步骤 | 解决方案 |
|---|---|---|---|
启用主题后整个页面变白，Network面板无任何++theme++请求 | manifest.cfg语法错误或缺失关键字段 | 1. 检查manifest.cfg是否有BOM或全角空格2. 运行 bin/instance debug进入调试模式，执行app.portal_themes.listThemes()看主题是否被识别 | 重写manifest.cfg，用vim -b检查BOM，确保title、version、base-theme三字段存在 |
页面有HTML结构但无样式，Network面板显示++theme++mytheme/css/main.css404 | CSS资源未正确注册或路径错误 | 1. 进入ZMIportal_css，确认mytheme-css条目存在且Enabled为True2. 在浏览器Console执行 window.themePath看是否返回/++theme++mytheme | 检查registry.xml中expression是否用${theme-path}而非硬编码；确认static/css/main.css文件存在且权限为644 |
| 页面样式部分生效，但某些元素错位 | rules.xml规则未覆盖到动态生成的class名 | 1. 用浏览器Inspector查看目标元素的实际class名 2. 对比 rules.xml中css:content值是否完全匹配 | 用css:content=".someClass.someOtherClass"替代css:content="#id"；启用development-mode = on实时调试 |
5.2 CSS加载顺序混乱导致样式覆盖失败
典型症状：自定义按钮样式button.my-btn { color: red; }不生效，浏览器开发者工具显示它被barceloneta-main.css里的button { color: blue; }覆盖。
根本原因：Plone的CSS Registry按注册顺序加载，barceloneta-main.css在mytheme-css之前加载，且button选择器权重更高。
独家技巧：用insert-before属性强制插入顺序。在registry.xml里：
<plone:staticResource name="mytheme-css" type="stylesheet" expression="string:${theme-path}/css/main.css" insert-before="barceloneta-main-css" <!-- 关键！ --> />如果barceloneta-main-css不存在（如Plone 5.1），用insert-after="plone-base-css"。我的经验是：永远把自定义CSS放在plone-base-css之后、barceloneta-main-css之前，这样既能继承基础样式，又能被主题样式覆盖。
5.3 Diazo规则不生效的隐藏陷阱
陷阱1：<replace>与<copy>的语义混淆
新手常写<replace css:theme="#nav" css:content=".portletNavigationTree"/>，结果导航栏内容为空。因为<replace>是替换整个节点，而.portletNavigationTree是端口容器，里面还有.portletHeader、.portletItem等子节点。正确做法是<copy>内容：
<copy css:theme="#nav" css:content=".portletNavigationTree .portletItem" />陷阱2：applyPrefix未启用导致图片路径404
CSS里写background: url(../images/logo.png);，但在portal_css里applyPrefix设为False，导致路径解析为/images/logo.png而非/++theme++mytheme/images/logo.png。解决方案：在ZMIportal_css里找到你的CSS条目，勾选Apply prefix，或在registry.xml里加：
<plone:staticResource name="mytheme-css" type="stylesheet" expression="string:${theme-path}/css/main.css" apply-prefix="true" <!-- 关键！ --> />陷阱3：<append>脚本执行时机错误
首页轮播图JS写<append css:theme-children="head"><script src="..."></script></append>，但脚本依赖document.getElementById('carousel')，而#carousel在<body>里，<head>里执行时DOM未就绪。解决方案：改用<append css:theme-children="body">，或在JS里包装document.addEventListener('DOMContentLoaded', ...)。
5.4 生产环境部署的终极 checklist
manifest.cfg检查：development-mode = off，version字段为语义化版本（如1.2.0），base-theme指向稳定版本（如plonetheme.barceloneta>=2.0.0,<3.0.0）静态资源压缩：在
buildout.cfg里启用plone.staticresources的压缩：[instance] eggs += plone.staticresources environment-vars += PLONE_STATIC_RESOURCES_COMPRESS=on PLONE_STATIC_RESOURCES_BUNDLES=on缓存头设置：在Nginx/Apache配置里，为
++theme++路径添加强缓存：location ~ ^/++theme\+\+.*\.(css|js|png|jpg|gif|svg)$ { expires 1